diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 7fa3637f7..bc5fb189f 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1,6 +1,6 @@ # These owners will be the default owners for everything in the repo. Unless a later match takes precedence, @global-owner1 and @global-owner2 will be requested for review when someone opens a pull request. -@slsriehl @bigcommerce/devdocs-codeowners @markcmurphy +@slsriehl @bigcommerce/dev-docs-team @markcmurphy # Teams can be specified as code owners as well. Teams should # be identified in the format @org/team-name. Teams must have diff --git a/.github/PULL_REQUEST_TEMPLATE/publication_pr_template.md b/.github/PULL_REQUEST_TEMPLATE/publication_pr_template.md deleted file mode 100644 index 0e3d44b2e..000000000 --- a/.github/PULL_REQUEST_TEMPLATE/publication_pr_template.md +++ /dev/null @@ -1,9 +0,0 @@ -# Publish with Rebase Merge - -## Included tickets / PRs -* [DEVDOCS-] - # -* [DEVDOCS-] - # -* [DEVDOCS-] - # - -## Additional information -Related Developer Center PRs, other related PRs, salient notes, etc. diff --git a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md deleted file mode 100644 index 597b0b3d5..000000000 --- a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md +++ /dev/null @@ -1,7 +0,0 @@ -# [DEVDOCS-] - -## What changed? -* present tense description of what changed - -## Anything else? -Related PRs, salient notes, etc. diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml new file mode 100644 index 000000000..a7b6505f9 --- /dev/null +++ b/.github/workflows/deploy.yml @@ -0,0 +1,18 @@ +name: Deploy + +on: + push: + branches: + - main + +jobs: + build: + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v2 + + - name: Trigger Vercel Deploy Hook + run: | + curl -X POST ${{ secrets.VERCEL_DEPLOY_HOOK_URL }} diff --git a/.stoplight.json b/.stoplight.json deleted file mode 100644 index 34fa7ec4e..000000000 --- a/.stoplight.json +++ /dev/null @@ -1,34 +0,0 @@ -{ - "formats": { - "openapi": { - "rootDir": "reference", - "include": [ - "**" - ] - }, - "markdown": { - "rootDir": "docs", - "include": [ - "**" - ] - }, - "image": { - "rootDir": "assets/images", - "include": [ - "**" - ] - }, - "json_schema": { - "rootDir": "models", - "include": [ - "**" - ] - } - }, - "exclude": [ - "README.md", - "CONTRIBUTING.md", - "pull_request_template_CODEOWNER.md", - "pull_request_template.md" - ] -} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e34c5e594..69da7de9e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,11 +1,13 @@ # Contributing to BigCommerce's API Specifications -Thanks for showing interest in contributing! +Thanks for your interest in contributing! ## Edit -* **Edit:** Fork the repository and edit with your preferred editor (we recommend [VS Code](https://code.visualstudio.com/) or [Stoplight Studio](https://meta.stoplight.io/docs/studio)). -* **Lint:** Check for errors using [Spectral](https://stoplight.io/open-source/spectral). -* **Commit:** Write good commit messages using the guidelines in the following section + +* **Edit:** Fork the repository and edit with your preferred editor. We recommend [VS Code](https://code.visualstudio.com/). +* **Lint:** Check for errors using [Spectral](https://stoplight.io/open-source/spectral) or another OAS linter. + +* **Commit:** Write good commit messages using the guidelines in the following section. * **Push** to your fork to ensure that your pull request contains the most up-to-date version of your code. ## Write descriptive commit messages @@ -16,11 +18,10 @@ Thanks for showing interest in contributing! * Use the imperative mood ("Fix broken link to x" not "Fixes broken link to x"). ## Pull request -[What is a pull request?](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request) -Internal users: Consult the repo's `internal_pr_template` to learn more about our pull request process. Then use the template to create your PR's description. +[What is a pull request?](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request) -External users: Consult the repo's `external_pr_template` to learn more about our pull request process. Then use the template to create your PR's description. +Use the included `pull_request_template.md` to tell us more about the changes you propose. ## Tools @@ -28,8 +29,7 @@ The following tools might be helpful. | Tool | Description | |:-----|:------------| -| [BigCommerce Stoplight Workspace](https://bigcommerce.stoplight.io/) | Our hosted documentation back end. <br> Contains editing tools for internal users.| -| [Spectral CLI](https://stoplight.io/open-source/spectral) | Node.js CLI for Stoplight's OpenAPI linter | -| [Spectral Linter for VS Code](https://marketplace.visualstudio.com/items?itemName=stoplight.spectral)| Stoplight's OpenAPI linter as a VS Code extension | +| [Spectral CLI](https://stoplight.io/open-source/spectral) | Node.js CLI for the Spectral OpenAPI linter | +| [Spectral Linter for VS Code](https://marketplace.visualstudio.com/items?itemName=stoplight.spectral)| The Spectral OpenAPI linter as a VS Code extension | | [swagger2openapi](https://www.npmjs.com/package/swagger2openapi)| Node.js CLI for converting Swagger to OpenAPI 3.0 | | [openapi.tools](https://openapi.tools/) | List of open-source OpenAPI tools | diff --git a/README.md b/README.md index 52f2d646f..e40852fe2 100644 --- a/README.md +++ b/README.md @@ -1,33 +1,34 @@ # BigCommerce API Specifications -OpenAPI Specifications (OAS) and JSON schema used to generate the human-readable [BigCommerce API Reference](https://developer.bigcommerce.com/api-reference). +This repo contains the OpenAPI Specifications (OAS) and JSON schema that form the human-readable [BigCommerce REST API Reference](https://developer.bigcommerce.com/docs/api). -<!-- theme: info --> -> #### OAS updates -> As of August 22, 2022, all API specification files are in OAS 3+ format. Please update your forks to ensure you're working with the newest source files. -> -> **Caveat:** The file that contains webhook events callback schemas, `webhooks_events.yml`, is still in Swagger 2.0 format. +As of August 22, 2022, all API specification files are in OAS 3+ format. We also made significant changes to this repo in March 2023. Please update your fork to ensure you're working with the newest source files. + +## Contributing + +If you're interested in contributing, see [CONTRIBUTING.md](CONTRIBUTING.md). ## Directory structure ```shell . -├── .circleci # config for circleci job that runs openapi linter - └── config.yml # - docs: https://meta.stoplight.io/docs/spectral -├── docs # markdown files -├── models # yaml schema for various objects - ├── ... - └── json2schema.py # script to easily convert json data to yaml schema -├── reference # openapi specification files +├── .github/ # github config + └── workflows/ # workflows to lint pull requests, etc. +├── .idea/ # directory ignored by git - use for yourself +├── models/ # yml schema for various objects + ├── email_templates/ # email template schemas + ├── webhooks/ # webhooks schemas + └── json2schema.py # script to convert json to yml +├── reference/ # openapi specification files + ├── catalog/ # catalog OAS API reference + ├── payments/ # payments OAS API reference + └── ... # other OAS API reference +├── .eslintrc.json # config for MDX linter ├── .gitignore # gitignore -├── .spectral.yaml # config for stoplight spectral openapi linter -├── .stoplight.json # Stoplight Platform edit view configuration file -├── CONTRIBUTING.md # guidelines for contribution -├── pull_request_template_CODEOWNER.md # template for codeowner dev merges -├── pull_request_template.md # template for most pull requests -└── toc.json # Stoplight Platform table of contents configuration file +├── .spectral.yaml # config for OAS linter +├── CONTRIBUTING # guidelines for contribution +├── package-lock.json +├── package.json +├── pull_request_template.md # template for most pull requests +└── README ``` - -## Contributing - -If you're interested in contributing, see [CONTRIBUTING.md](CONTRIBUTING.md). diff --git a/assets/html/graphql-explorer.html b/assets/html/graphql-explorer.html deleted file mode 100644 index 4485b68d0..000000000 --- a/assets/html/graphql-explorer.html +++ /dev/null @@ -1,30 +0,0 @@ -<!DOCTYPE html> -<html> - <head> - <script src="https://cdn.jsdelivr.net/npm/react@16/umd/react.production.min.js"></script> - <script src="https://cdn.jsdelivr.net/npm/react-dom@16/umd/react-dom.production.min.js"></script> - - <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/graphql-voyager/dist/voyager.css" /> - <script src="https://cdn.jsdelivr.net/npm/graphql-voyager/dist/voyager.min.js"></script> - </head> - <body> - <div id="voyager">Loading...</div> - <script> - function introspectionProvider(query) { - return fetch('https://{$$.env.default_storefront_hostname}/graphql', { - method: 'post', - headers: { - 'Content-Type': 'application/json', - 'Authorization': 'Bearer {$$.env.default_storefront_token}' - }, - body: JSON.stringify({query: query}), - }).then(response => response.json()); - } - - // Render <Voyager /> - GraphQLVoyager.init(document.getElementById('voyager'), { - introspection: introspectionProvider - }) - </script> - </body> -</html> diff --git a/assets/html/graphql-playground.html b/assets/html/graphql-playground.html deleted file mode 100644 index 54b7f2dc0..000000000 --- a/assets/html/graphql-playground.html +++ /dev/null @@ -1,11865 +0,0 @@ -<style>@charset "UTF-8";/*! normalize.css v8.0.0 | MIT License | github.com/necolas/normalize.css */html{line-height:1.15;-webkit-text-size-adjust:100%}body{margin:0}h1{font-size:2em;margin:.67em 0}hr{box-sizing:content-box;height:0;overflow:visible}pre{font-family:monospace,monospace;font-size:1em}a{background-color:transparent}abbr[title]{border-bottom:none;text-decoration:underline;text-decoration:underline dotted}b,strong{font-weight:bolder}code,kbd,samp{font-family:monospace,monospace;font-size:1em}small{font-size:80%}sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}sub{bottom:-.25em}sup{top:-.5em}img{border-style:none}button,input,optgroup,select,textarea{font-family:inherit;font-size:100%;line-height:1.15;margin:0}button,input{overflow:visible}button,select{text-transform:none}[type=button],[type=reset],[type=submit],button{-webkit-appearance:button}[type=button]::-moz-focus-inner,[type=reset]::-moz-focus-inner,[type=submit]::-moz-focus-inner,button::-moz-focus-inner{border-style:none;padding:0}[type=button]:-moz-focusring,[type=reset]:-moz-focusring,[type=submit]:-moz-focusring,button:-moz-focusring{outline:1px dotted ButtonText}fieldset{padding:.35em .75em .625em}legend{box-sizing:border-box;color:inherit;display:table;max-width:100%;padding:0;white-space:normal}progress{vertical-align:baseline}textarea{overflow:auto}[type=checkbox],[type=radio]{box-sizing:border-box;padding:0}[type=number]::-webkit-inner-spin-button,[type=number]::-webkit-outer-spin-button{height:auto}[type=search]{-webkit-appearance:textfield;outline-offset:-2px}[type=search]::-webkit-search-decoration{-webkit-appearance:none}::-webkit-file-upload-button{-webkit-appearance:button;font:inherit}details{display:block}summary{display:list-item}template{display:none}[hidden]{display:none}.foundation-mq{font-family:"small=0em&medium=40em&large=64em&xlarge=75em&xxlarge=90em"}html{box-sizing:border-box;font-size:95%}*,::after,::before{box-sizing:inherit}body{margin:0;padding:0;background:#fefefe;font-family:"Source Sans Pro",sans-serif;font-weight:400;line-height:1.5;color:#2d3134;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}img{display:inline-block;vertical-align:middle;max-width:100%;height:auto;-ms-interpolation-mode:bicubic}textarea{height:auto;min-height:50px;border-radius:0}select{box-sizing:border-box;width:100%;border-radius:0}.map_canvas embed,.map_canvas img,.map_canvas object,.mqa-display embed,.mqa-display img,.mqa-display object{max-width:none!important}button{padding:0;appearance:none;border:0;border-radius:0;background:0 0;line-height:1;cursor:auto}[data-whatinput=mouse] button{outline:0}pre{overflow:auto}button,input,optgroup,select,textarea{font-family:inherit}.is-visible{display:block!important}.is-hidden{display:none!important}.row{max-width:auto;margin-right:auto;margin-left:auto}.row::after,.row::before{display:table;content:" ";flex-basis:0;order:1}.row::after{clear:both}.row.collapse>.column,.row.collapse>.columns{padding-right:0;padding-left:0}.row .row{margin-right:-.6578947368rem;margin-left:-.6578947368rem}@media print,screen and (min-width:40em){.row .row{margin-right:-.9868421053rem;margin-left:-.9868421053rem}}@media print,screen and (min-width:64em){.row .row{margin-right:-.9868421053rem;margin-left:-.9868421053rem}}.row .row.collapse{margin-right:0;margin-left:0}.row.expanded{max-width:none}.row.expanded .row{margin-right:auto;margin-left:auto}.row:not(.expanded) .row{max-width:none}.row.gutter-small>.column,.row.gutter-small>.columns{padding-right:.6578947368rem;padding-left:.6578947368rem}.row.gutter-medium>.column,.row.gutter-medium>.columns{padding-right:.9868421053rem;padding-left:.9868421053rem}.column,.columns{width:100%;float:left;padding-right:.6578947368rem;padding-left:.6578947368rem}@media print,screen and (min-width:40em){.column,.columns{padding-right:.9868421053rem;padding-left:.9868421053rem}}.column,.column:last-child:not(:first-child),.columns{float:left;clear:none}.column:last-child:not(:first-child),.columns:last-child:not(:first-child){float:right}.column.end:last-child:last-child,.end.columns:last-child:last-child{float:left}.column.row.row,.row.row.columns{float:none}.row .column.row.row,.row .row.row.columns{margin-right:0;margin-left:0;padding-right:0;padding-left:0}.small-1{width:8.3333333333%}.small-push-1{position:relative;left:8.3333333333%}.small-pull-1{position:relative;left:-8.3333333333%}.small-offset-0{margin-left:0}.small-2{width:16.6666666667%}.small-push-2{position:relative;left:16.6666666667%}.small-pull-2{position:relative;left:-16.6666666667%}.small-offset-1{margin-left:8.3333333333%}.small-3{width:25%}.small-push-3{position:relative;left:25%}.small-pull-3{position:relative;left:-25%}.small-offset-2{margin-left:16.6666666667%}.small-4{width:33.3333333333%}.small-push-4{position:relative;left:33.3333333333%}.small-pull-4{position:relative;left:-33.3333333333%}.small-offset-3{margin-left:25%}.small-5{width:41.6666666667%}.small-push-5{position:relative;left:41.6666666667%}.small-pull-5{position:relative;left:-41.6666666667%}.small-offset-4{margin-left:33.3333333333%}.small-6{width:50%}.small-push-6{position:relative;left:50%}.small-pull-6{position:relative;left:-50%}.small-offset-5{margin-left:41.6666666667%}.small-7{width:58.3333333333%}.small-push-7{position:relative;left:58.3333333333%}.small-pull-7{position:relative;left:-58.3333333333%}.small-offset-6{margin-left:50%}.small-8{width:66.6666666667%}.small-push-8{position:relative;left:66.6666666667%}.small-pull-8{position:relative;left:-66.6666666667%}.small-offset-7{margin-left:58.3333333333%}.small-9{width:75%}.small-push-9{position:relative;left:75%}.small-pull-9{position:relative;left:-75%}.small-offset-8{margin-left:66.6666666667%}.small-10{width:83.3333333333%}.small-push-10{position:relative;left:83.3333333333%}.small-pull-10{position:relative;left:-83.3333333333%}.small-offset-9{margin-left:75%}.small-11{width:91.6666666667%}.small-push-11{position:relative;left:91.6666666667%}.small-pull-11{position:relative;left:-91.6666666667%}.small-offset-10{margin-left:83.3333333333%}.small-12{width:100%}.small-offset-11{margin-left:91.6666666667%}.small-up-1>.column,.small-up-1>.columns{float:left;width:100%}.small-up-1>.column:nth-of-type(1n),.small-up-1>.columns:nth-of-type(1n){clear:none}.small-up-1>.column:nth-of-type(1n+1),.small-up-1>.columns:nth-of-type(1n+1){clear:both}.small-up-1>.column:last-child,.small-up-1>.columns:last-child{float:left}.small-up-2>.column,.small-up-2>.columns{float:left;width:50%}.small-up-2>.column:nth-of-type(1n),.small-up-2>.columns:nth-of-type(1n){clear:none}.small-up-2>.column:nth-of-type(2n+1),.small-up-2>.columns:nth-of-type(2n+1){clear:both}.small-up-2>.column:last-child,.small-up-2>.columns:last-child{float:left}.small-up-3>.column,.small-up-3>.columns{float:left;width:33.3333333333%}.small-up-3>.column:nth-of-type(1n),.small-up-3>.columns:nth-of-type(1n){clear:none}.small-up-3>.column:nth-of-type(3n+1),.small-up-3>.columns:nth-of-type(3n+1){clear:both}.small-up-3>.column:last-child,.small-up-3>.columns:last-child{float:left}.small-up-4>.column,.small-up-4>.columns{float:left;width:25%}.small-up-4>.column:nth-of-type(1n),.small-up-4>.columns:nth-of-type(1n){clear:none}.small-up-4>.column:nth-of-type(4n+1),.small-up-4>.columns:nth-of-type(4n+1){clear:both}.small-up-4>.column:last-child,.small-up-4>.columns:last-child{float:left}.small-up-5>.column,.small-up-5>.columns{float:left;width:20%}.small-up-5>.column:nth-of-type(1n),.small-up-5>.columns:nth-of-type(1n){clear:none}.small-up-5>.column:nth-of-type(5n+1),.small-up-5>.columns:nth-of-type(5n+1){clear:both}.small-up-5>.column:last-child,.small-up-5>.columns:last-child{float:left}.small-up-6>.column,.small-up-6>.columns{float:left;width:16.6666666667%}.small-up-6>.column:nth-of-type(1n),.small-up-6>.columns:nth-of-type(1n){clear:none}.small-up-6>.column:nth-of-type(6n+1),.small-up-6>.columns:nth-of-type(6n+1){clear:both}.small-up-6>.column:last-child,.small-up-6>.columns:last-child{float:left}.small-up-7>.column,.small-up-7>.columns{float:left;width:14.2857142857%}.small-up-7>.column:nth-of-type(1n),.small-up-7>.columns:nth-of-type(1n){clear:none}.small-up-7>.column:nth-of-type(7n+1),.small-up-7>.columns:nth-of-type(7n+1){clear:both}.small-up-7>.column:last-child,.small-up-7>.columns:last-child{float:left}.small-up-8>.column,.small-up-8>.columns{float:left;width:12.5%}.small-up-8>.column:nth-of-type(1n),.small-up-8>.columns:nth-of-type(1n){clear:none}.small-up-8>.column:nth-of-type(8n+1),.small-up-8>.columns:nth-of-type(8n+1){clear:both}.small-up-8>.column:last-child,.small-up-8>.columns:last-child{float:left}.small-collapse>.column,.small-collapse>.columns{padding-right:0;padding-left:0}.small-collapse .row{margin-right:0;margin-left:0}.expanded.row .small-collapse.row{margin-right:0;margin-left:0}.small-uncollapse>.column,.small-uncollapse>.columns{padding-right:.6578947368rem;padding-left:.6578947368rem}.small-centered{margin-right:auto;margin-left:auto}.small-centered,.small-centered:last-child:not(:first-child){float:none;clear:both}.small-pull-0,.small-push-0,.small-uncentered{position:static;margin-right:0;margin-left:0}.small-pull-0,.small-pull-0:last-child:not(:first-child),.small-push-0,.small-push-0:last-child:not(:first-child),.small-uncentered,.small-uncentered:last-child:not(:first-child){float:left;clear:none}.small-pull-0:last-child:not(:first-child),.small-push-0:last-child:not(:first-child),.small-uncentered:last-child:not(:first-child){float:right}@media print,screen and (min-width:40em){.medium-1{width:8.3333333333%}.medium-push-1{position:relative;left:8.3333333333%}.medium-pull-1{position:relative;left:-8.3333333333%}.medium-offset-0{margin-left:0}.medium-2{width:16.6666666667%}.medium-push-2{position:relative;left:16.6666666667%}.medium-pull-2{position:relative;left:-16.6666666667%}.medium-offset-1{margin-left:8.3333333333%}.medium-3{width:25%}.medium-push-3{position:relative;left:25%}.medium-pull-3{position:relative;left:-25%}.medium-offset-2{margin-left:16.6666666667%}.medium-4{width:33.3333333333%}.medium-push-4{position:relative;left:33.3333333333%}.medium-pull-4{position:relative;left:-33.3333333333%}.medium-offset-3{margin-left:25%}.medium-5{width:41.6666666667%}.medium-push-5{position:relative;left:41.6666666667%}.medium-pull-5{position:relative;left:-41.6666666667%}.medium-offset-4{margin-left:33.3333333333%}.medium-6{width:50%}.medium-push-6{position:relative;left:50%}.medium-pull-6{position:relative;left:-50%}.medium-offset-5{margin-left:41.6666666667%}.medium-7{width:58.3333333333%}.medium-push-7{position:relative;left:58.3333333333%}.medium-pull-7{position:relative;left:-58.3333333333%}.medium-offset-6{margin-left:50%}.medium-8{width:66.6666666667%}.medium-push-8{position:relative;left:66.6666666667%}.medium-pull-8{position:relative;left:-66.6666666667%}.medium-offset-7{margin-left:58.3333333333%}.medium-9{width:75%}.medium-push-9{position:relative;left:75%}.medium-pull-9{position:relative;left:-75%}.medium-offset-8{margin-left:66.6666666667%}.medium-10{width:83.3333333333%}.medium-push-10{position:relative;left:83.3333333333%}.medium-pull-10{position:relative;left:-83.3333333333%}.medium-offset-9{margin-left:75%}.medium-11{width:91.6666666667%}.medium-push-11{position:relative;left:91.6666666667%}.medium-pull-11{position:relative;left:-91.6666666667%}.medium-offset-10{margin-left:83.3333333333%}.medium-12{width:100%}.medium-offset-11{margin-left:91.6666666667%}.medium-up-1>.column,.medium-up-1>.columns{float:left;width:100%}.medium-up-1>.column:nth-of-type(1n),.medium-up-1>.columns:nth-of-type(1n){clear:none}.medium-up-1>.column:nth-of-type(1n+1),.medium-up-1>.columns:nth-of-type(1n+1){clear:both}.medium-up-1>.column:last-child,.medium-up-1>.columns:last-child{float:left}.medium-up-2>.column,.medium-up-2>.columns{float:left;width:50%}.medium-up-2>.column:nth-of-type(1n),.medium-up-2>.columns:nth-of-type(1n){clear:none}.medium-up-2>.column:nth-of-type(2n+1),.medium-up-2>.columns:nth-of-type(2n+1){clear:both}.medium-up-2>.column:last-child,.medium-up-2>.columns:last-child{float:left}.medium-up-3>.column,.medium-up-3>.columns{float:left;width:33.3333333333%}.medium-up-3>.column:nth-of-type(1n),.medium-up-3>.columns:nth-of-type(1n){clear:none}.medium-up-3>.column:nth-of-type(3n+1),.medium-up-3>.columns:nth-of-type(3n+1){clear:both}.medium-up-3>.column:last-child,.medium-up-3>.columns:last-child{float:left}.medium-up-4>.column,.medium-up-4>.columns{float:left;width:25%}.medium-up-4>.column:nth-of-type(1n),.medium-up-4>.columns:nth-of-type(1n){clear:none}.medium-up-4>.column:nth-of-type(4n+1),.medium-up-4>.columns:nth-of-type(4n+1){clear:both}.medium-up-4>.column:last-child,.medium-up-4>.columns:last-child{float:left}.medium-up-5>.column,.medium-up-5>.columns{float:left;width:20%}.medium-up-5>.column:nth-of-type(1n),.medium-up-5>.columns:nth-of-type(1n){clear:none}.medium-up-5>.column:nth-of-type(5n+1),.medium-up-5>.columns:nth-of-type(5n+1){clear:both}.medium-up-5>.column:last-child,.medium-up-5>.columns:last-child{float:left}.medium-up-6>.column,.medium-up-6>.columns{float:left;width:16.6666666667%}.medium-up-6>.column:nth-of-type(1n),.medium-up-6>.columns:nth-of-type(1n){clear:none}.medium-up-6>.column:nth-of-type(6n+1),.medium-up-6>.columns:nth-of-type(6n+1){clear:both}.medium-up-6>.column:last-child,.medium-up-6>.columns:last-child{float:left}.medium-up-7>.column,.medium-up-7>.columns{float:left;width:14.2857142857%}.medium-up-7>.column:nth-of-type(1n),.medium-up-7>.columns:nth-of-type(1n){clear:none}.medium-up-7>.column:nth-of-type(7n+1),.medium-up-7>.columns:nth-of-type(7n+1){clear:both}.medium-up-7>.column:last-child,.medium-up-7>.columns:last-child{float:left}.medium-up-8>.column,.medium-up-8>.columns{float:left;width:12.5%}.medium-up-8>.column:nth-of-type(1n),.medium-up-8>.columns:nth-of-type(1n){clear:none}.medium-up-8>.column:nth-of-type(8n+1),.medium-up-8>.columns:nth-of-type(8n+1){clear:both}.medium-up-8>.column:last-child,.medium-up-8>.columns:last-child{float:left}.medium-collapse>.column,.medium-collapse>.columns{padding-right:0;padding-left:0}.medium-collapse .row{margin-right:0;margin-left:0}.expanded.row .medium-collapse.row{margin-right:0;margin-left:0}.medium-uncollapse>.column,.medium-uncollapse>.columns{padding-right:.9868421053rem;padding-left:.9868421053rem}.medium-centered{margin-right:auto;margin-left:auto}.medium-centered,.medium-centered:last-child:not(:first-child){float:none;clear:both}.medium-pull-0,.medium-push-0,.medium-uncentered{position:static;margin-right:0;margin-left:0}.medium-pull-0,.medium-pull-0:last-child:not(:first-child),.medium-push-0,.medium-push-0:last-child:not(:first-child),.medium-uncentered,.medium-uncentered:last-child:not(:first-child){float:left;clear:none}.medium-pull-0:last-child:not(:first-child),.medium-push-0:last-child:not(:first-child),.medium-uncentered:last-child:not(:first-child){float:right}}@media print,screen and (min-width:64em){.large-1{width:8.3333333333%}.large-push-1{position:relative;left:8.3333333333%}.large-pull-1{position:relative;left:-8.3333333333%}.large-offset-0{margin-left:0}.large-2{width:16.6666666667%}.large-push-2{position:relative;left:16.6666666667%}.large-pull-2{position:relative;left:-16.6666666667%}.large-offset-1{margin-left:8.3333333333%}.large-3{width:25%}.large-push-3{position:relative;left:25%}.large-pull-3{position:relative;left:-25%}.large-offset-2{margin-left:16.6666666667%}.large-4{width:33.3333333333%}.large-push-4{position:relative;left:33.3333333333%}.large-pull-4{position:relative;left:-33.3333333333%}.large-offset-3{margin-left:25%}.large-5{width:41.6666666667%}.large-push-5{position:relative;left:41.6666666667%}.large-pull-5{position:relative;left:-41.6666666667%}.large-offset-4{margin-left:33.3333333333%}.large-6{width:50%}.large-push-6{position:relative;left:50%}.large-pull-6{position:relative;left:-50%}.large-offset-5{margin-left:41.6666666667%}.large-7{width:58.3333333333%}.large-push-7{position:relative;left:58.3333333333%}.large-pull-7{position:relative;left:-58.3333333333%}.large-offset-6{margin-left:50%}.large-8{width:66.6666666667%}.large-push-8{position:relative;left:66.6666666667%}.large-pull-8{position:relative;left:-66.6666666667%}.large-offset-7{margin-left:58.3333333333%}.large-9{width:75%}.large-push-9{position:relative;left:75%}.large-pull-9{position:relative;left:-75%}.large-offset-8{margin-left:66.6666666667%}.large-10{width:83.3333333333%}.large-push-10{position:relative;left:83.3333333333%}.large-pull-10{position:relative;left:-83.3333333333%}.large-offset-9{margin-left:75%}.large-11{width:91.6666666667%}.large-push-11{position:relative;left:91.6666666667%}.large-pull-11{position:relative;left:-91.6666666667%}.large-offset-10{margin-left:83.3333333333%}.large-12{width:100%}.large-offset-11{margin-left:91.6666666667%}.large-up-1>.column,.large-up-1>.columns{float:left;width:100%}.large-up-1>.column:nth-of-type(1n),.large-up-1>.columns:nth-of-type(1n){clear:none}.large-up-1>.column:nth-of-type(1n+1),.large-up-1>.columns:nth-of-type(1n+1){clear:both}.large-up-1>.column:last-child,.large-up-1>.columns:last-child{float:left}.large-up-2>.column,.large-up-2>.columns{float:left;width:50%}.large-up-2>.column:nth-of-type(1n),.large-up-2>.columns:nth-of-type(1n){clear:none}.large-up-2>.column:nth-of-type(2n+1),.large-up-2>.columns:nth-of-type(2n+1){clear:both}.large-up-2>.column:last-child,.large-up-2>.columns:last-child{float:left}.large-up-3>.column,.large-up-3>.columns{float:left;width:33.3333333333%}.large-up-3>.column:nth-of-type(1n),.large-up-3>.columns:nth-of-type(1n){clear:none}.large-up-3>.column:nth-of-type(3n+1),.large-up-3>.columns:nth-of-type(3n+1){clear:both}.large-up-3>.column:last-child,.large-up-3>.columns:last-child{float:left}.large-up-4>.column,.large-up-4>.columns{float:left;width:25%}.large-up-4>.column:nth-of-type(1n),.large-up-4>.columns:nth-of-type(1n){clear:none}.large-up-4>.column:nth-of-type(4n+1),.large-up-4>.columns:nth-of-type(4n+1){clear:both}.large-up-4>.column:last-child,.large-up-4>.columns:last-child{float:left}.large-up-5>.column,.large-up-5>.columns{float:left;width:20%}.large-up-5>.column:nth-of-type(1n),.large-up-5>.columns:nth-of-type(1n){clear:none}.large-up-5>.column:nth-of-type(5n+1),.large-up-5>.columns:nth-of-type(5n+1){clear:both}.large-up-5>.column:last-child,.large-up-5>.columns:last-child{float:left}.large-up-6>.column,.large-up-6>.columns{float:left;width:16.6666666667%}.large-up-6>.column:nth-of-type(1n),.large-up-6>.columns:nth-of-type(1n){clear:none}.large-up-6>.column:nth-of-type(6n+1),.large-up-6>.columns:nth-of-type(6n+1){clear:both}.large-up-6>.column:last-child,.large-up-6>.columns:last-child{float:left}.large-up-7>.column,.large-up-7>.columns{float:left;width:14.2857142857%}.large-up-7>.column:nth-of-type(1n),.large-up-7>.columns:nth-of-type(1n){clear:none}.large-up-7>.column:nth-of-type(7n+1),.large-up-7>.columns:nth-of-type(7n+1){clear:both}.large-up-7>.column:last-child,.large-up-7>.columns:last-child{float:left}.large-up-8>.column,.large-up-8>.columns{float:left;width:12.5%}.large-up-8>.column:nth-of-type(1n),.large-up-8>.columns:nth-of-type(1n){clear:none}.large-up-8>.column:nth-of-type(8n+1),.large-up-8>.columns:nth-of-type(8n+1){clear:both}.large-up-8>.column:last-child,.large-up-8>.columns:last-child{float:left}.large-collapse>.column,.large-collapse>.columns{padding-right:0;padding-left:0}.large-collapse .row{margin-right:0;margin-left:0}.expanded.row .large-collapse.row{margin-right:0;margin-left:0}.large-uncollapse>.column,.large-uncollapse>.columns{padding-right:.9868421053rem;padding-left:.9868421053rem}.large-centered{margin-right:auto;margin-left:auto}.large-centered,.large-centered:last-child:not(:first-child){float:none;clear:both}.large-pull-0,.large-push-0,.large-uncentered{position:static;margin-right:0;margin-left:0}.large-pull-0,.large-pull-0:last-child:not(:first-child),.large-push-0,.large-push-0:last-child:not(:first-child),.large-uncentered,.large-uncentered:last-child:not(:first-child){float:left;clear:none}.large-pull-0:last-child:not(:first-child),.large-push-0:last-child:not(:first-child),.large-uncentered:last-child:not(:first-child){float:right}}.column-block{margin-bottom:1.3157894737rem}.column-block>:last-child{margin-bottom:0}@media print,screen and (min-width:40em){.column-block{margin-bottom:1.9736842105rem}.column-block>:last-child{margin-bottom:0}}blockquote,dd,div,dl,dt,form,h1,h2,h3,h4,h5,h6,li,ol,p,pre,td,th,ul{margin:0;padding:0}p{margin-bottom:1rem;font-size:inherit;line-height:1.6;text-rendering:optimizeLegibility}em,i{font-style:italic;line-height:inherit}b,strong{font-weight:700;line-height:inherit}small{font-size:80%;line-height:inherit}.h1,.h2,.h3,.h4,.h5,.h6,h1,h2,h3,h4,h5,h6{font-family:"Source Sans Pro",sans-serif;font-style:normal;font-weight:400;color:inherit;text-rendering:optimizeLegibility}.h1 small,.h2 small,.h3 small,.h4 small,.h5 small,.h6 small,h1 small,h2 small,h3 small,h4 small,h5 small,h6 small{line-height:0;color:#cacaca}.h1,h1{font-size:1.5789473684rem;line-height:1.4;margin-top:0;margin-bottom:.5rem}.h2,h2{font-size:1.3157894737rem;line-height:1.4;margin-top:0;margin-bottom:.5rem}.h3,h3{font-size:1.25rem;line-height:1.4;margin-top:0;margin-bottom:.5rem}.h4,h4{font-size:1.1842105263rem;line-height:1.4;margin-top:0;margin-bottom:.5rem}.h5,h5{font-size:1.1184210526rem;line-height:1.4;margin-top:0;margin-bottom:.5rem}.h6,h6{font-size:1.0526315789rem;line-height:1.4;margin-top:0;margin-bottom:.5rem}@media print,screen and (min-width:40em){.h1,h1{font-size:1.7105263158rem}.h2,h2{font-size:1.5789473684rem}.h3,h3{font-size:1.3157894737rem}.h4,h4{font-size:1.1842105263rem}.h5,h5{font-size:1.1184210526rem}.h6,h6{font-size:1.0526315789rem}}a{line-height:inherit;color:#1779ba;text-decoration:none;cursor:pointer}a:focus,a:hover{color:#1468a0}a img{border:0}hr{clear:both;max-width:auto;height:0;margin:1.3157894737rem auto;border-top:0;border-right:0;border-bottom:1px solid #cacaca;border-left:0}dl,ol,ul{margin-bottom:1rem;list-style-position:outside;line-height:1.6}li{font-size:inherit}ul{margin-left:1.25rem;list-style-type:disc}ol{margin-left:1.25rem}ol ol,ol ul,ul ol,ul ul{margin-left:1.25rem;margin-bottom:0}dl{margin-bottom:1rem}dl dt{margin-bottom:.3rem;font-weight:700}blockquote{margin:0 0 1rem;padding:.5921052632rem 1.3157894737rem 0 1.25rem;border-left:1px solid #cacaca}blockquote,blockquote p{line-height:1.6;color:#8a8a8a}abbr,abbr[title]{border-bottom:1px dotted #2d3134;cursor:help;text-decoration:none}figure{margin:0}kbd{margin:0;padding:.1315789474rem .2631578947rem 0;background-color:#e6e6e6;font-family:Consolas,"Liberation Mono",Courier,monospace;color:#2d3134}.subheader{margin-top:.2rem;margin-bottom:.5rem;font-weight:400;line-height:1.4;color:#8a8a8a}.lead{font-size:118.75%;line-height:1.6}.stat{font-size:2.5rem;line-height:1}p+.stat{margin-top:-1rem}ol.no-bullet,ul.no-bullet{margin-left:0;list-style:none}.cite-block,cite{display:block;color:#8a8a8a;font-size:.8552631579rem}.cite-block:before,cite:before{content:"— "}.code-inline,code{border:1px solid #cacaca;background-color:#e6e6e6;font-family:Consolas,"Liberation Mono",Courier,monospace;font-weight:400;color:#2d3134;display:inline;max-width:100%;word-wrap:break-word;padding:.0657894737rem .0657894737rem .0657894737rem}.code-block{border:1px solid #cacaca;background-color:#e6e6e6;font-family:Consolas,"Liberation Mono",Courier,monospace;font-weight:400;color:#2d3134;display:block;overflow:auto;white-space:pre;padding:1rem;margin-bottom:1.5rem}.text-left{text-align:left}.text-right{text-align:right}.text-center{text-align:center}.text-justify{text-align:justify}@media print,screen and (min-width:40em){.medium-text-left{text-align:left}.medium-text-right{text-align:right}.medium-text-center{text-align:center}.medium-text-justify{text-align:justify}}@media print,screen and (min-width:64em){.large-text-left{text-align:left}.large-text-right{text-align:right}.large-text-center{text-align:center}.large-text-justify{text-align:justify}}.show-for-print{display:none!important}@media print{*{background:0 0!important;color:#000!important;color-adjust:economy;box-shadow:none!important;text-shadow:none!important}.show-for-print{display:block!important}.hide-for-print{display:none!important}table.show-for-print{display:table!important}thead.show-for-print{display:table-header-group!important}tbody.show-for-print{display:table-row-group!important}tr.show-for-print{display:table-row!important}td.show-for-print{display:table-cell!important}th.show-for-print{display:table-cell!important}a,a:visited{text-decoration:underline}a[href]:after{content:" (" attr(href) ")"}.ir a:after,a[href^="#"]:after,a[href^="javascript:"]:after{content:""}abbr[title]:after{content:" (" attr(title) ")"}blockquote,pre{border:1px solid #8a8a8a;page-break-inside:avoid}thead{display:table-header-group}img,tr{page-break-inside:avoid}img{max-width:100%!important}@page{margin:.5cm}h2,h3,p{orphans:3;widows:3}h2,h3{page-break-after:avoid}.print-break-inside{page-break-inside:auto}}.button{display:inline-block;vertical-align:middle;margin:0 0 1rem 0;padding:.85em 1em;border:1px solid transparent;border-radius:0;transition:background-color .25s ease-out,color .25s ease-out;font-family:inherit;font-size:.9rem;-webkit-appearance:none;line-height:1;text-align:center;cursor:pointer}[data-whatinput=mouse] .button{outline:0}.button.tiny{font-size:.6rem}.button.small{font-size:.75rem}.button.large{font-size:1.25rem}.button.expanded{display:block;width:100%;margin-right:0;margin-left:0}.button,.button.disabled,.button.disabled:focus,.button.disabled:hover,.button[disabled],.button[disabled]:focus,.button[disabled]:hover{background-color:#1779ba;color:#fefefe}.button:focus,.button:hover{background-color:#14679e;color:#fefefe}.button.primary,.button.primary.disabled,.button.primary.disabled:focus,.button.primary.disabled:hover,.button.primary[disabled],.button.primary[disabled]:focus,.button.primary[disabled]:hover{background-color:#1779ba;color:#fefefe}.button.primary:focus,.button.primary:hover{background-color:#126195;color:#fefefe}.button.secondary,.button.secondary.disabled,.button.secondary.disabled:focus,.button.secondary.disabled:hover,.button.secondary[disabled],.button.secondary[disabled]:focus,.button.secondary[disabled]:hover{background-color:#767676;color:#fefefe}.button.secondary:focus,.button.secondary:hover{background-color:#5e5e5e;color:#fefefe}.button.success,.button.success.disabled,.button.success.disabled:focus,.button.success.disabled:hover,.button.success[disabled],.button.success[disabled]:focus,.button.success[disabled]:hover{background-color:#3adb76;color:#2d3134}.button.success:focus,.button.success:hover{background-color:#22bb5b;color:#2d3134}.button.warning,.button.warning.disabled,.button.warning.disabled:focus,.button.warning.disabled:hover,.button.warning[disabled],.button.warning[disabled]:focus,.button.warning[disabled]:hover{background-color:#ffae00;color:#2d3134}.button.warning:focus,.button.warning:hover{background-color:#cc8b00;color:#2d3134}.button.alert,.button.alert.disabled,.button.alert.disabled:focus,.button.alert.disabled:hover,.button.alert[disabled],.button.alert[disabled]:focus,.button.alert[disabled]:hover{background-color:#fcd7d8;color:#2d3134}.button.alert:focus,.button.alert:hover{background-color:#f58083;color:#2d3134}.button.hollow,.button.hollow.disabled,.button.hollow.disabled:focus,.button.hollow.disabled:hover,.button.hollow:focus,.button.hollow:hover,.button.hollow[disabled],.button.hollow[disabled]:focus,.button.hollow[disabled]:hover{background-color:transparent}.button.hollow,.button.hollow.disabled,.button.hollow.disabled:focus,.button.hollow.disabled:hover,.button.hollow[disabled],.button.hollow[disabled]:focus,.button.hollow[disabled]:hover{border:1px solid #1779ba;color:#1779ba}.button.hollow:focus,.button.hollow:hover{border-color:#0c3d5d;color:#0c3d5d}.button.hollow.primary,.button.hollow.primary.disabled,.button.hollow.primary.disabled:focus,.button.hollow.primary.disabled:hover,.button.hollow.primary[disabled],.button.hollow.primary[disabled]:focus,.button.hollow.primary[disabled]:hover{border:1px solid #1779ba;color:#1779ba}.button.hollow.primary:focus,.button.hollow.primary:hover{border-color:#0c3d5d;color:#0c3d5d}.button.hollow.secondary,.button.hollow.secondary.disabled,.button.hollow.secondary.disabled:focus,.button.hollow.secondary.disabled:hover,.button.hollow.secondary[disabled],.button.hollow.secondary[disabled]:focus,.button.hollow.secondary[disabled]:hover{border:1px solid #767676;color:#767676}.button.hollow.secondary:focus,.button.hollow.secondary:hover{border-color:#3b3b3b;color:#3b3b3b}.button.hollow.success,.button.hollow.success.disabled,.button.hollow.success.disabled:focus,.button.hollow.success.disabled:hover,.button.hollow.success[disabled],.button.hollow.success[disabled]:focus,.button.hollow.success[disabled]:hover{border:1px solid #3adb76;color:#3adb76}.button.hollow.success:focus,.button.hollow.success:hover{border-color:#157539;color:#157539}.button.hollow.warning,.button.hollow.warning.disabled,.button.hollow.warning.disabled:focus,.button.hollow.warning.disabled:hover,.button.hollow.warning[disabled],.button.hollow.warning[disabled]:focus,.button.hollow.warning[disabled]:hover{border:1px solid #ffae00;color:#ffae00}.button.hollow.warning:focus,.button.hollow.warning:hover{border-color:#805700;color:#805700}.button.hollow.alert,.button.hollow.alert.disabled,.button.hollow.alert.disabled:focus,.button.hollow.alert.disabled:hover,.button.hollow.alert[disabled],.button.hollow.alert[disabled]:focus,.button.hollow.alert[disabled]:hover{border:1px solid #fcd7d8;color:#fcd7d8}.button.hollow.alert:focus,.button.hollow.alert:hover{border-color:#d91016;color:#d91016}.button.clear,.button.clear.disabled,.button.clear.disabled:focus,.button.clear.disabled:hover,.button.clear:focus,.button.clear:hover,.button.clear[disabled],.button.clear[disabled]:focus,.button.clear[disabled]:hover{border-color:transparent;background-color:transparent}.button.clear,.button.clear.disabled,.button.clear.disabled:focus,.button.clear.disabled:hover,.button.clear[disabled],.button.clear[disabled]:focus,.button.clear[disabled]:hover{color:#1779ba}.button.clear:focus,.button.clear:hover{color:#0c3d5d}.button.clear.primary,.button.clear.primary.disabled,.button.clear.primary.disabled:focus,.button.clear.primary.disabled:hover,.button.clear.primary[disabled],.button.clear.primary[disabled]:focus,.button.clear.primary[disabled]:hover{color:#1779ba}.button.clear.primary:focus,.button.clear.primary:hover{color:#0c3d5d}.button.clear.secondary,.button.clear.secondary.disabled,.button.clear.secondary.disabled:focus,.button.clear.secondary.disabled:hover,.button.clear.secondary[disabled],.button.clear.secondary[disabled]:focus,.button.clear.secondary[disabled]:hover{color:#767676}.button.clear.secondary:focus,.button.clear.secondary:hover{color:#3b3b3b}.button.clear.success,.button.clear.success.disabled,.button.clear.success.disabled:focus,.button.clear.success.disabled:hover,.button.clear.success[disabled],.button.clear.success[disabled]:focus,.button.clear.success[disabled]:hover{color:#3adb76}.button.clear.success:focus,.button.clear.success:hover{color:#157539}.button.clear.warning,.button.clear.warning.disabled,.button.clear.warning.disabled:focus,.button.clear.warning.disabled:hover,.button.clear.warning[disabled],.button.clear.warning[disabled]:focus,.button.clear.warning[disabled]:hover{color:#ffae00}.button.clear.warning:focus,.button.clear.warning:hover{color:#805700}.button.clear.alert,.button.clear.alert.disabled,.button.clear.alert.disabled:focus,.button.clear.alert.disabled:hover,.button.clear.alert[disabled],.button.clear.alert[disabled]:focus,.button.clear.alert[disabled]:hover{color:#fcd7d8}.button.clear.alert:focus,.button.clear.alert:hover{color:#d91016}.button.disabled,.button[disabled]{opacity:.25;cursor:not-allowed}.button.dropdown::after{display:block;width:0;height:0;border:inset .4em;content:"";border-bottom-width:0;border-top-style:solid;border-color:#fefefe transparent transparent;position:relative;top:.4em;display:inline-block;float:right;margin-left:1em}.button.dropdown.clear::after,.button.dropdown.hollow::after{border-top-color:#1779ba}.button.dropdown.clear.primary::after,.button.dropdown.hollow.primary::after{border-top-color:#1779ba}.button.dropdown.clear.secondary::after,.button.dropdown.hollow.secondary::after{border-top-color:#767676}.button.dropdown.clear.success::after,.button.dropdown.hollow.success::after{border-top-color:#3adb76}.button.dropdown.clear.warning::after,.button.dropdown.hollow.warning::after{border-top-color:#ffae00}.button.dropdown.clear.alert::after,.button.dropdown.hollow.alert::after{border-top-color:#fcd7d8}.button.arrow-only::after{top:-.1em;float:none;margin-left:0}a.button:focus,a.button:hover{text-decoration:none}[type=color],[type=date],[type=datetime-local],[type=datetime],[type=email],[type=month],[type=number],[type=password],[type=search],[type=tel],[type=text],[type=time],[type=url],[type=week],textarea{display:block;box-sizing:border-box;width:100%;height:2.5657894737rem;margin:0 0 1.0526315789rem;padding:.5263157895rem;border:1px solid #cacaca;border-radius:0;background-color:#fefefe;box-shadow:inset 0 1px 2px rgba(45,49,52,.1);font-family:inherit;font-size:1.0526315789rem;font-weight:400;line-height:1.5;color:#2d3134;transition:box-shadow .5s,border-color .25s ease-in-out;appearance:none}[type=color]:focus,[type=date]:focus,[type=datetime-local]:focus,[type=datetime]:focus,[type=email]:focus,[type=month]:focus,[type=number]:focus,[type=password]:focus,[type=search]:focus,[type=tel]:focus,[type=text]:focus,[type=time]:focus,[type=url]:focus,[type=week]:focus,textarea:focus{outline:0;border:1px solid #8a8a8a;background-color:#fefefe;box-shadow:0 0 5px #cacaca;transition:box-shadow .5s,border-color .25s ease-in-out}textarea{max-width:100%}textarea[rows]{height:auto}input:disabled,input[readonly],textarea:disabled,textarea[readonly]{background-color:#e6e6e6;cursor:not-allowed}[type=button],[type=submit]{appearance:none;border-radius:0}input[type=search]{box-sizing:border-box}::placeholder{color:#cacaca}[type=checkbox],[type=file],[type=radio]{margin:0 0 1.0526315789rem}[type=checkbox]+label,[type=radio]+label{display:inline-block;vertical-align:baseline;margin-left:.5263157895rem;margin-right:1.0526315789rem;margin-bottom:0}[type=checkbox]+label[for],[type=radio]+label[for]{cursor:pointer}label>[type=checkbox],label>[type=radio]{margin-right:.5263157895rem}[type=file]{width:100%}label{display:block;margin:0;font-size:.9210526316rem;font-weight:400;line-height:1.8;color:#2d3134}label.middle{margin:0 0 1.0526315789rem;padding:.5921052632rem 0}.help-text{margin-top:-.5263157895rem;font-size:.8552631579rem;font-style:italic;color:#2d3134}.input-group{display:flex;width:100%;margin-bottom:1.0526315789rem;align-items:stretch}.input-group>:first-child,.input-group>:first-child.input-group-button>*{border-radius:0}.input-group>:last-child,.input-group>:last-child.input-group-button>*{border-radius:0}.input-group-button,.input-group-button a,.input-group-button button,.input-group-button input,.input-group-button label,.input-group-field,.input-group-label{margin:0;white-space:nowrap}.input-group-label{padding:0 1rem;border:1px solid #cacaca;background:#e6e6e6;color:#2d3134;text-align:center;white-space:nowrap;display:flex;flex:0 0 auto;align-items:center}.input-group-label:first-child{border-right:0}.input-group-label:last-child{border-left:0}.input-group-field{border-radius:0;flex:1 1 0px;min-width:0}.input-group-button{padding-top:0;padding-bottom:0;text-align:center;display:flex;flex:0 0 auto}.input-group-button a,.input-group-button button,.input-group-button input,.input-group-button label{align-self:stretch;height:auto;padding-top:0;padding-bottom:0;font-size:1.0526315789rem}fieldset{margin:0;padding:0;border:0}legend{max-width:100%;margin-bottom:.5263157895rem}.fieldset{margin:1.1842105263rem 0;padding:1.3157894737rem;border:1px solid #cacaca}.fieldset legend{margin:0;margin-left:-.1973684211rem;padding:0 .1973684211rem}select{height:2.5657894737rem;margin:0 0 1.0526315789rem;padding:.5263157895rem;appearance:none;border:1px solid #cacaca;border-radius:0;background-color:#fefefe;font-family:inherit;font-size:1.0526315789rem;font-weight:400;line-height:1.5;color:#2d3134;background-image:url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' version='1.1' width='32' height='24' viewBox='0 0 32 24'><polygon points='0,0 32,0 16,24' style='fill: rgb%28138, 138, 138%29'></polygon></svg>");background-origin:content-box;background-position:right -1.0526315789rem center;background-repeat:no-repeat;background-size:9px 6px;padding-right:1.5789473684rem;transition:box-shadow .5s,border-color .25s ease-in-out}@media screen and (min-width:0\0){select{background-image:url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAYCAYAAACbU/80AAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAAIpJREFUeNrEkckNgDAMBBfRkEt0ObRBBdsGXUDgmQfK4XhH2m8czQAAy27R3tsw4Qfe2x8uOO6oYLb6GlOor3GF+swURAOmUJ+RwtEJs9WvTGEYxBXqI1MQAZhCfUQKRzDMVj+TwrAIV6jvSUEkYAr1LSkcyTBb/V+KYfX7xAeusq3sLDtGH3kEGACPWIflNZfhRQAAAABJRU5ErkJggg==)}}select:focus{outline:0;border:1px solid #8a8a8a;background-color:#fefefe;box-shadow:0 0 5px #cacaca;transition:box-shadow .5s,border-color .25s ease-in-out}select:disabled{background-color:#e6e6e6;cursor:not-allowed}select::-ms-expand{display:none}select[multiple]{height:auto;background-image:none}select:not([multiple]){padding-top:0;padding-bottom:0}.is-invalid-input:not(:focus){border-color:#fcd7d8;background-color:#fefafa}.is-invalid-input:not(:focus)::placeholder{color:#fcd7d8}.is-invalid-label{color:#fcd7d8}.form-error{display:none;margin-top:-.5263157895rem;margin-bottom:1.0526315789rem;font-size:.7894736842rem;font-weight:700;color:#fcd7d8}.form-error.is-visible{display:block}.hide{display:none!important}.invisible{visibility:hidden}@media print,screen and (max-width:39.99875em){.hide-for-small-only{display:none!important}}@media screen and (max-width:0em),screen and (min-width:40em){.show-for-small-only{display:none!important}}@media print,screen and (min-width:40em){.hide-for-medium{display:none!important}}@media screen and (max-width:39.99875em){.show-for-medium{display:none!important}}@media print,screen and (min-width:40em) and (max-width:63.99875em){.hide-for-medium-only{display:none!important}}@media screen and (max-width:39.99875em),screen and (min-width:64em){.show-for-medium-only{display:none!important}}@media print,screen and (min-width:64em){.hide-for-large{display:none!important}}@media screen and (max-width:63.99875em){.show-for-large{display:none!important}}@media print,screen and (min-width:64em) and (max-width:74.99875em){.hide-for-large-only{display:none!important}}@media screen and (max-width:63.99875em),screen and (min-width:75em){.show-for-large-only{display:none!important}}.show-for-sr,.show-on-focus{position:absolute!important;width:1px!important;height:1px!important;padding:0!important;overflow:hidden!important;clip:rect(0,0,0,0)!important;white-space:nowrap!important;border:0!important}.show-on-focus:active,.show-on-focus:focus{position:static!important;width:auto!important;height:auto!important;overflow:visible!important;clip:auto!important;white-space:normal!important}.hide-for-portrait,.show-for-landscape{display:block!important}@media screen and (orientation:landscape){.hide-for-portrait,.show-for-landscape{display:block!important}}@media screen and (orientation:portrait){.hide-for-portrait,.show-for-landscape{display:none!important}}.hide-for-landscape,.show-for-portrait{display:none!important}@media screen and (orientation:landscape){.hide-for-landscape,.show-for-portrait{display:none!important}}@media screen and (orientation:portrait){.hide-for-landscape,.show-for-portrait{display:block!important}}.float-left{float:left!important}.float-right{float:right!important}.float-center{display:block;margin-right:auto;margin-left:auto}.clearfix::after,.clearfix::before{display:table;content:" ";flex-basis:0;order:1}.clearfix::after{clear:both}.close-button{position:absolute;z-index:10;color:#8a8a8a;cursor:pointer}[data-whatinput=mouse] .close-button{outline:0}.close-button:focus,.close-button:hover{color:#2d3134}.close-button.small{right:.66rem;top:.33em;font-size:1.5em;line-height:1}.close-button,.close-button.medium{right:1rem;top:.5rem;font-size:2em;line-height:1}.label{display:inline-block;padding:.33333rem .5rem;border-radius:0;font-size:.8rem;line-height:1;white-space:nowrap;cursor:default;background:#1779ba;color:#fefefe}.label.primary{background:#1779ba;color:#fefefe}.label.secondary{background:#767676;color:#fefefe}.label.success{background:#3adb76;color:#2d3134}.label.warning{background:#ffae00;color:#2d3134}.label.alert{background:#fcd7d8;color:#2d3134}table{border-collapse:collapse;width:100%;margin-bottom:1rem;border-radius:0}tbody,tfoot,thead{border:1px solid #f1f1f1;background-color:#fefefe}caption{padding:.5263157895rem .6578947368rem .6578947368rem;font-weight:700}thead{background:#f8f8f8;color:#2d3134}tfoot{background:#f1f1f1;color:#2d3134}tfoot tr,thead tr{background:0 0}tfoot td,tfoot th,thead td,thead th{padding:.5263157895rem .6578947368rem .6578947368rem;font-weight:700;text-align:left}tbody td,tbody th{padding:.5263157895rem .6578947368rem .6578947368rem}tbody tr{border-bottom:0;border-bottom:1px solid #f1f1f1;background-color:#fefefe}table.striped tbody tr:nth-child(even){border-bottom:0;background-color:#f1f1f1}@media print,screen and (max-width:63.99875em){table.stack thead{display:none}table.stack tfoot{display:none}table.stack td,table.stack th,table.stack tr{display:block}table.stack td{border-top:0}}table.scroll{display:block;width:100%;overflow-x:auto}table.hover thead tr:hover{background-color:#f3f3f3}table.hover tfoot tr:hover{background-color:#ececec}table.hover tbody tr:hover{background-color:#f9f9f9}table.hover.striped tr:nth-of-type(even):hover{background-color:#ececec}.table-scroll{overflow-x:auto}#spectacle ::selection{background-color:#cce2ff;color:rgba(0,0,0,.87)}#spectacle ::-webkit-scrollbar{width:5px;height:5px}#spectacle ::-webkit-scrollbar-thumb{background:#d3d5d5}@media (min-width:48em){#spectacle #sidebar .close-button{display:none}}#spectacle .swagger-operation-path:before{content:"Path";display:block;margin-bottom:.5em;color:#838383}#spectacle .swagger-operation-description:before{content:"Description";display:block;margin-bottom:.5em;color:#838383}#spectacle .swagger-operation-deprecated:after{display:inline-block;padding:.33333rem .5rem;border-radius:0;font-size:.8rem;line-height:1;white-space:nowrap;cursor:default;font-size:.9rem;border-radius:4px;padding:3px 6px;text-transform:uppercase;color:#f36a6e;content:"Deprecated"}#spectacle .swagger-request-params:before{content:"Arguments";display:block;margin-bottom:.5em;color:#838383}#spectacle .swagger-request-body:before{content:"";display:block;margin-bottom:.5em;color:#838383}#spectacle .swagger-request-body .json-schema-properties-base:before,#spectacle .swagger-request-body .json-schema-properties-blank:before,#spectacle .swagger-request-body .json-schema-properties:before{display:none}#spectacle .swagger-responses:before{content:"Response";display:block;margin-bottom:.5em;color:#838383}#spectacle .swagger-global:before{display:inline-block;padding:.33333rem .5rem;border-radius:0;font-size:.8rem;line-height:1;white-space:nowrap;cursor:default;font-size:.9rem;border-radius:4px;padding:3px 6px;background:#fcd7d8;color:#2d3134;content:"global"}#spectacle table.table th.swagger-param-key{width:auto}#spectacle table.table th.swagger-param-key:before{content:"Key"}#spectacle table.table th.swagger-param-name{width:auto}#spectacle table.table th.swagger-param-name:before{content:"Name"}#spectacle table.table th.swagger-param-description{width:auto}#spectacle table.table th.swagger-param-description:before{content:"Description"}#spectacle table.table th.swagger-param-data-type{width:auto}#spectacle table.table th.swagger-param-data-type:before{content:"Data type"}#spectacle table.table th.swagger-param-type{width:auto}#spectacle table.table th.swagger-param-type:before{content:"Type"}#spectacle table.table th.swagger-request-security-schema{width:auto}#spectacle table.table th.swagger-request-security-schema:before{content:"Schema"}#spectacle table.table th.swagger-request-security-scopes{width:auto}#spectacle table.table th.swagger-request-security-scopes:before{content:"Scopes"}#spectacle table.table th.swagger-response-header-name{width:auto}#spectacle table.table th.swagger-response-header-name:before{content:"Header"}#spectacle table.table th.swagger-response-header-description{width:auto}#spectacle table.table th.swagger-response-header-description:before{content:"Description"}#spectacle table.table th.swagger-response-header-data-type{width:auto}#spectacle table.table th.swagger-response-header-data-type:before{content:"Data type"}#spectacle table.table th.swagger-response-code{width:auto}#spectacle table.table th.swagger-response-code:before{content:"Code"}#spectacle table.table th.swagger-response-description{width:auto}#spectacle table.table th.swagger-response-description:before{content:"Description"}#spectacle table.table th.swagger-response-schema{width:auto}#spectacle table.table th.swagger-response-schema:before{content:"Schema"}#spectacle .swagger-response-name-value{font-weight:700}#spectacle .swagger-response-description-text{padding-bottom:.5em}#spectacle .swagger-request-security:before{content:"Security";display:block;margin-bottom:.5em;color:#838383}#spectacle .swagger-security-definition-basic:before{color:#cacaca;content:"(HTTP Basic Authentication)"}#spectacle .swagger-security-definition-oauth2:before{color:#cacaca;content:"(OAuth2 Authentication)"}#spectacle .swagger-security-definition-apiKey:before{color:#cacaca;content:"(API Key Authentication)"}#spectacle .json-schema-properties tbody,#spectacle .json-schema-properties-base tbody,#spectacle .json-schema-properties-blank tbody,#spectacle .swagger-request-params tbody{border:none!important}#spectacle .json-schema-properties tbody tr,#spectacle .json-schema-properties-base tbody tr,#spectacle .json-schema-properties-blank tbody tr,#spectacle .swagger-request-params tbody tr{border-bottom:none!important;vertical-align:top}#spectacle .json-schema-properties tbody tr th,#spectacle .json-schema-properties-base tbody tr th,#spectacle .json-schema-properties-blank tbody tr th,#spectacle .swagger-request-params tbody tr th{border-bottom:2px solid #000}#spectacle .json-schema-properties tbody tr td,#spectacle .json-schema-properties-base tbody tr td,#spectacle .json-schema-properties-blank tbody tr td,#spectacle .swagger-request-params tbody tr td{border-top:1px solid #e6e6e6}#spectacle .json-schema-properties tbody tr td.no-top-border,#spectacle .json-schema-properties-base tbody tr td.no-top-border,#spectacle .json-schema-properties-blank tbody tr td.no-top-border,#spectacle .swagger-request-params tbody tr td.no-top-border{border-top:none!important}#spectacle .json-schema-properties td,#spectacle .json-schema-properties th,#spectacle .json-schema-properties-base td,#spectacle .json-schema-properties-base th,#spectacle .json-schema-properties-blank td,#spectacle .json-schema-properties-blank th,#spectacle .swagger-request-params td,#spectacle .swagger-request-params th{padding:5px}#spectacle .json-schema-properties td:first-child,#spectacle .json-schema-properties th:first-child,#spectacle .json-schema-properties-base td:first-child,#spectacle .json-schema-properties-base th:first-child,#spectacle .json-schema-properties-blank td:first-child,#spectacle .json-schema-properties-blank th:first-child,#spectacle .swagger-request-params td:first-child,#spectacle .swagger-request-params th:first-child{padding-left:0}#spectacle .json-schema-properties td:last-child,#spectacle .json-schema-properties th:last-child,#spectacle .json-schema-properties-base td:last-child,#spectacle .json-schema-properties-base th:last-child,#spectacle .json-schema-properties-blank td:last-child,#spectacle .json-schema-properties-blank th:last-child,#spectacle .swagger-request-params td:last-child,#spectacle .swagger-request-params th:last-child{padding-right:0}#spectacle .json-schema-properties th,#spectacle .json-schema-properties-base th,#spectacle .json-schema-properties-blank th,#spectacle .swagger-request-params th{text-align:left;font-weight:700}#spectacle a>code{color:#1779ba}#spectacle .field-arguments{background-color:#fafbfc;border:1px #e6e6e6 solid;padding-left:10px;padding-top:10px}#spectacle .field-arguments p{margin-bottom:.25rem}#spectacle .field-arguments .field-argument{border-top:1px #e6e6e6 solid;margin-bottom:.5rem}#spectacle .field-arguments .field-argument .field-argument-name{padding-top:5px}#spectacle .json-schema-properties dl,#spectacle .json-schema-properties-base dl,#spectacle .json-schema-properties-blank dl{margin:0}#spectacle .json-schema-properties dt,#spectacle .json-schema-properties-base dt,#spectacle .json-schema-properties-blank dt{margin-bottom:.25rem}#spectacle .json-schema-properties dt.has-description,#spectacle .json-schema-properties-base dt.has-description,#spectacle .json-schema-properties-blank dt.has-description{margin-bottom:0}#spectacle .json-schema-properties dd,#spectacle .json-schema-properties-base dd,#spectacle .json-schema-properties-blank dd{color:#8a8a8a}#spectacle .json-schema-properties dd:not(:last-child),#spectacle .json-schema-properties-base dd:not(:last-child),#spectacle .json-schema-properties-blank dd:not(:last-child){padding-bottom:.5rem}#spectacle .json-schema-properties:before{content:"Fields";display:block;margin-bottom:.5em;color:#838383}#spectacle .json-schema-description+.json-schema-properties,#spectacle .json-schema-description+.json-schema-properties-base,#spectacle .json-schema-description+.json-schema-properties-blank{margin-top:1.5rem}#spectacle .json-schema-ref-array:before{color:#8a8a8a;content:"Array["}#spectacle .json-schema-ref-array:after{color:#8a8a8a;content:"]"}#spectacle .json-schema-example:before{content:"Example";display:block;margin-bottom:.5em;color:#838383}#spectacle .json-schema-array-items:before{content:"Items";display:block;margin-bottom:.5em;color:#838383}#spectacle .json-schema-allOf-inherited:before{content:"Inherited";display:block;margin-bottom:.5em;color:#838383}#spectacle .json-schema-anyOf>dl{padding-left:1em}#spectacle .json-schema-anyOf>dl dt:not(:first-child):before{content:"or "}#spectacle .json-schema-anyOf>dl dt:first-child:before{content:"either "}#spectacle .json-schema-additionalProperties:before{content:"Additional properties";display:block;margin-bottom:.5em;color:#838383}#spectacle .json-inner-schema .json-schema-array-items,#spectacle .json-inner-schema .json-schema-description,#spectacle .json-inner-schema .json-schema-example,#spectacle .json-inner-schema .json-schema-properties,#spectacle .json-inner-schema .json-schema-properties-base,#spectacle .json-inner-schema .json-schema-properties-blank{padding-left:1em;margin-top:.5em;padding-bottom:.5em}#spectacle .json-property-discriminator:before{display:inline-block;padding:.33333rem .5rem;border-radius:0;font-size:.8rem;line-height:1;white-space:nowrap;cursor:default;font-size:.9rem;border-radius:4px;padding:3px 6px;background:#fcd7d8;color:#2d3134;content:"discriminator"}#spectacle .json-property-required:before{display:inline-block;padding:.33333rem .5rem;border-radius:0;font-size:.8rem;line-height:1;white-space:nowrap;cursor:default;font-size:.9rem;border-radius:4px;padding:3px 6px;background:#fcd7d8;color:#2d3134;content:"required"}#spectacle .json-property-not-nullable:before{display:inline-block;padding:.33333rem .5rem;border-radius:0;font-size:.8rem;line-height:1;white-space:nowrap;cursor:default;font-size:.9rem;border-radius:4px;padding:3px 6px;background:#fcd7d8;color:#2d3134;content:"not-nullable"}#spectacle .json-property-read-only:before{display:inline-block;padding:.33333rem .5rem;border-radius:0;font-size:.8rem;line-height:1;white-space:nowrap;cursor:default;font-size:.9rem;border-radius:4px;padding:3px 6px;background:#fcd7d8;color:#2d3134;content:"read only"}#spectacle .json-property-format{font-style:italic}#spectacle .json-property-enum:before{content:"enum: ["}#spectacle .json-property-enum:after{content:"]"}#spectacle .json-property-default-value:before{content:"default: "}#spectacle .json-property-range:empty{display:none!important}#spectacle .json-property-range:before{content:"range: "}#spectacle .json-property-enum-item{font-weight:lighter;font-size:small}#spectacle .json-schema-reference{font-size:90%}#spectacle .no-padding{padding:0!important}#spectacle .no-margin{margin:0!important}#spectacle button:focus{outline:0}#spectacle .default-label{display:inline-block;padding:.33333rem .5rem;border-radius:0;font-size:.8rem;line-height:1;white-space:nowrap;cursor:default;font-size:.75rem;border-radius:4px;padding:3px 6px;background:#767676;color:#fefefe}#spectacle #logo{text-align:center;padding-right:.5rem;padding-top:1rem;padding-bottom:.25rem}#spectacle #logo img{max-height:75px}#spectacle .row,#spectacle article .doc-row,#spectacle article .prop-row{max-width:auto;margin-right:auto;margin-left:auto}#spectacle .row::after,#spectacle .row::before,#spectacle article .doc-row::after,#spectacle article .doc-row::before,#spectacle article .prop-row::after,#spectacle article .prop-row::before{display:table;content:" ";flex-basis:0;order:1}#spectacle .row::after,#spectacle article .doc-row::after,#spectacle article .prop-row::after{clear:both}#spectacle .row.collapse>.column,#spectacle .row.collapse>.columns,#spectacle article .doc-row>.column,#spectacle article .doc-row>.columns,#spectacle article .doc-row>.doc-copy,#spectacle article .doc-row>.doc-examples,#spectacle article .prop-row .doc-row>.prop-name,#spectacle article .prop-row .doc-row>.prop-value,#spectacle article .prop-row .row.collapse>.prop-name,#spectacle article .prop-row .row.collapse>.prop-value,#spectacle article .prop-row>.column,#spectacle article .prop-row>.columns,#spectacle article .prop-row>.doc-copy,#spectacle article .prop-row>.doc-examples,#spectacle article .prop-row>.prop-name,#spectacle article .prop-row>.prop-value,#spectacle article .row.collapse>.doc-copy,#spectacle article .row.collapse>.doc-examples{padding-right:0;padding-left:0}#spectacle .row .row,#spectacle .row article .doc-row,#spectacle .row article .prop-row,#spectacle article .doc-row .doc-row,#spectacle article .doc-row .prop-row,#spectacle article .doc-row .row,#spectacle article .prop-row .doc-row,#spectacle article .prop-row .prop-row,#spectacle article .prop-row .row,#spectacle article .row .doc-row,#spectacle article .row .prop-row{margin-right:-.6578947368rem;margin-left:-.6578947368rem}@media print,screen and (min-width:40em){#spectacle .row .row,#spectacle .row article .doc-row,#spectacle .row article .prop-row,#spectacle article .doc-row .doc-row,#spectacle article .doc-row .prop-row,#spectacle article .doc-row .row,#spectacle article .prop-row .doc-row,#spectacle article .prop-row .prop-row,#spectacle article .prop-row .row,#spectacle article .row .doc-row,#spectacle article .row .prop-row{margin-right:-.9868421053rem;margin-left:-.9868421053rem}}@media print,screen and (min-width:64em){#spectacle .row .row,#spectacle .row article .doc-row,#spectacle .row article .prop-row,#spectacle article .doc-row .doc-row,#spectacle article .doc-row .prop-row,#spectacle article .doc-row .row,#spectacle article .prop-row .doc-row,#spectacle article .prop-row .prop-row,#spectacle article .prop-row .row,#spectacle article .row .doc-row,#spectacle article .row .prop-row{margin-right:-.9868421053rem;margin-left:-.9868421053rem}}#spectacle .row .row.collapse,#spectacle .row article .doc-row,#spectacle .row article .prop-row,#spectacle article .doc-row .doc-row,#spectacle article .doc-row .prop-row,#spectacle article .doc-row .row.collapse,#spectacle article .prop-row .doc-row,#spectacle article .prop-row .prop-row,#spectacle article .prop-row .row.collapse,#spectacle article .row .doc-row,#spectacle article .row .prop-row{margin-right:0;margin-left:0}#spectacle .row.expanded,#spectacle article .expanded.doc-row,#spectacle article .expanded.prop-row{max-width:none}#spectacle .row.expanded .row,#spectacle .row.expanded article .doc-row,#spectacle .row.expanded article .prop-row,#spectacle article .expanded.doc-row .doc-row,#spectacle article .expanded.doc-row .prop-row,#spectacle article .expanded.doc-row .row,#spectacle article .expanded.prop-row .doc-row,#spectacle article .expanded.prop-row .prop-row,#spectacle article .expanded.prop-row .row,#spectacle article .row.expanded .doc-row,#spectacle article .row.expanded .prop-row{margin-right:auto;margin-left:auto}#spectacle .row:not(.expanded) .row,#spectacle .row:not(.expanded) article .doc-row,#spectacle .row:not(.expanded) article .prop-row,#spectacle article .doc-row:not(.expanded) .doc-row,#spectacle article .doc-row:not(.expanded) .prop-row,#spectacle article .doc-row:not(.expanded) .row,#spectacle article .prop-row:not(.expanded) .doc-row,#spectacle article .prop-row:not(.expanded) .prop-row,#spectacle article .prop-row:not(.expanded) .row,#spectacle article .row:not(.expanded) .doc-row,#spectacle article .row:not(.expanded) .prop-row{max-width:none}#spectacle .row.gutter-small>.column,#spectacle .row.gutter-small>.columns,#spectacle article .gutter-small.doc-row>.column,#spectacle article .gutter-small.doc-row>.columns,#spectacle article .gutter-small.doc-row>.doc-copy,#spectacle article .gutter-small.doc-row>.doc-examples,#spectacle article .gutter-small.prop-row>.column,#spectacle article .gutter-small.prop-row>.columns,#spectacle article .gutter-small.prop-row>.doc-copy,#spectacle article .gutter-small.prop-row>.doc-examples,#spectacle article .gutter-small.prop-row>.prop-name,#spectacle article .gutter-small.prop-row>.prop-value,#spectacle article .prop-row .gutter-small.doc-row>.prop-name,#spectacle article .prop-row .gutter-small.doc-row>.prop-value,#spectacle article .prop-row .row.gutter-small>.prop-name,#spectacle article .prop-row .row.gutter-small>.prop-value,#spectacle article .row.gutter-small>.doc-copy,#spectacle article .row.gutter-small>.doc-examples{padding-right:.6578947368rem;padding-left:.6578947368rem}#spectacle .row.gutter-medium>.column,#spectacle .row.gutter-medium>.columns,#spectacle article .gutter-medium.doc-row>.column,#spectacle article .gutter-medium.doc-row>.columns,#spectacle article .gutter-medium.doc-row>.doc-copy,#spectacle article .gutter-medium.doc-row>.doc-examples,#spectacle article .gutter-medium.prop-row>.column,#spectacle article .gutter-medium.prop-row>.columns,#spectacle article .gutter-medium.prop-row>.doc-copy,#spectacle article .gutter-medium.prop-row>.doc-examples,#spectacle article .gutter-medium.prop-row>.prop-name,#spectacle article .gutter-medium.prop-row>.prop-value,#spectacle article .prop-row .gutter-medium.doc-row>.prop-name,#spectacle article .prop-row .gutter-medium.doc-row>.prop-value,#spectacle article .prop-row .row.gutter-medium>.prop-name,#spectacle article .prop-row .row.gutter-medium>.prop-value,#spectacle article .row.gutter-medium>.doc-copy,#spectacle article .row.gutter-medium>.doc-examples{padding-right:.9868421053rem;padding-left:.9868421053rem}#spectacle .column,#spectacle .columns,#spectacle article .doc-copy,#spectacle article .doc-examples,#spectacle article .prop-row .prop-name,#spectacle article .prop-row .prop-value{width:100%;float:left;padding-right:.6578947368rem;padding-left:.6578947368rem}@media print,screen and (min-width:40em){#spectacle .column,#spectacle .columns,#spectacle article .doc-copy,#spectacle article .doc-examples,#spectacle article .prop-row .prop-name,#spectacle article .prop-row .prop-value{padding-right:.9868421053rem;padding-left:.9868421053rem}}#spectacle .column,#spectacle .column:last-child:not(:first-child),#spectacle .columns,#spectacle article .doc-copy,#spectacle article .doc-examples,#spectacle article .prop-row .prop-name,#spectacle article .prop-row .prop-value{float:left;clear:none}#spectacle .column:last-child:not(:first-child),#spectacle .columns:last-child:not(:first-child),#spectacle article .doc-copy:last-child:not(:first-child),#spectacle article .doc-examples:last-child:not(:first-child),#spectacle article .prop-row .prop-name:last-child:not(:first-child),#spectacle article .prop-row .prop-value:last-child:not(:first-child){float:right}#spectacle .column.end:last-child:last-child,#spectacle .end.columns:last-child:last-child,#spectacle article .end.doc-copy:last-child:last-child,#spectacle article .end.doc-examples:last-child:last-child,#spectacle article .prop-row .end.prop-name:last-child:last-child,#spectacle article .prop-row .end.prop-value:last-child:last-child{float:left}#spectacle .column.row.row,#spectacle .row.row.columns,#spectacle article .column.doc-row,#spectacle article .column.prop-row,#spectacle article .columns.doc-row,#spectacle article .columns.prop-row,#spectacle article .doc-row.doc-copy,#spectacle article .doc-row.doc-examples,#spectacle article .prop-row .prop-name.doc-row,#spectacle article .prop-row .prop-row.prop-name,#spectacle article .prop-row .prop-row.prop-value,#spectacle article .prop-row .prop-value.doc-row,#spectacle article .prop-row .row.row.prop-name,#spectacle article .prop-row .row.row.prop-value,#spectacle article .prop-row.doc-copy,#spectacle article .prop-row.doc-examples,#spectacle article .row.row.doc-copy,#spectacle article .row.row.doc-examples{float:none}#spectacle .row .column.row.row,#spectacle .row .row.row.columns,#spectacle .row article .column.doc-row,#spectacle .row article .column.prop-row,#spectacle .row article .columns.doc-row,#spectacle .row article .columns.prop-row,#spectacle .row article .doc-row.doc-copy,#spectacle .row article .doc-row.doc-examples,#spectacle .row article .prop-row.doc-copy,#spectacle .row article .prop-row.doc-examples,#spectacle .row article .row.row.doc-copy,#spectacle .row article .row.row.doc-examples,#spectacle article .doc-row .column.doc-row,#spectacle article .doc-row .column.prop-row,#spectacle article .doc-row .column.row.row,#spectacle article .doc-row .columns.doc-row,#spectacle article .doc-row .columns.prop-row,#spectacle article .doc-row .doc-row.doc-copy,#spectacle article .doc-row .doc-row.doc-examples,#spectacle article .doc-row .prop-row.doc-copy,#spectacle article .doc-row .prop-row.doc-examples,#spectacle article .doc-row .row.row.columns,#spectacle article .doc-row .row.row.doc-copy,#spectacle article .doc-row .row.row.doc-examples,#spectacle article .prop-row .column.doc-row,#spectacle article .prop-row .column.prop-row,#spectacle article .prop-row .column.row.row,#spectacle article .prop-row .columns.doc-row,#spectacle article .prop-row .columns.prop-row,#spectacle article .prop-row .doc-row.doc-copy,#spectacle article .prop-row .doc-row.doc-examples,#spectacle article .prop-row .prop-name.doc-row,#spectacle article .prop-row .prop-row.doc-copy,#spectacle article .prop-row .prop-row.doc-examples,#spectacle article .prop-row .prop-row.prop-name,#spectacle article .prop-row .prop-row.prop-value,#spectacle article .prop-row .prop-value.doc-row,#spectacle article .prop-row .row.row.columns,#spectacle article .prop-row .row.row.doc-copy,#spectacle article .prop-row .row.row.doc-examples,#spectacle article .prop-row .row.row.prop-name,#spectacle article .prop-row .row.row.prop-value,#spectacle article .row .column.doc-row,#spectacle article .row .column.prop-row,#spectacle article .row .columns.doc-row,#spectacle article .row .columns.prop-row,#spectacle article .row .doc-row.doc-copy,#spectacle article .row .doc-row.doc-examples,#spectacle article .row .prop-row.doc-copy,#spectacle article .row .prop-row.doc-examples,#spectacle article .row .row.row.doc-copy,#spectacle article .row .row.row.doc-examples{margin-right:0;margin-left:0;padding-right:0;padding-left:0}#spectacle .small-1{width:8.3333333333%}#spectacle .small-push-1{position:relative;left:8.3333333333%}#spectacle .small-pull-1{position:relative;left:-8.3333333333%}#spectacle .small-offset-0{margin-left:0}#spectacle .small-2{width:16.6666666667%}#spectacle .small-push-2{position:relative;left:16.6666666667%}#spectacle .small-pull-2{position:relative;left:-16.6666666667%}#spectacle .small-offset-1{margin-left:8.3333333333%}#spectacle .small-3{width:25%}#spectacle .small-push-3{position:relative;left:25%}#spectacle .small-pull-3{position:relative;left:-25%}#spectacle .small-offset-2{margin-left:16.6666666667%}#spectacle .small-4{width:33.3333333333%}#spectacle .small-push-4{position:relative;left:33.3333333333%}#spectacle .small-pull-4{position:relative;left:-33.3333333333%}#spectacle .small-offset-3{margin-left:25%}#spectacle .small-5,#spectacle article .prop-row .prop-name{width:41.6666666667%}#spectacle .small-push-5{position:relative;left:41.6666666667%}#spectacle .small-pull-5{position:relative;left:-41.6666666667%}#spectacle .small-offset-4{margin-left:33.3333333333%}#spectacle .small-6{width:50%}#spectacle .small-push-6{position:relative;left:50%}#spectacle .small-pull-6{position:relative;left:-50%}#spectacle .small-offset-5{margin-left:41.6666666667%}#spectacle .small-7,#spectacle article .prop-row .prop-value{width:58.3333333333%}#spectacle .small-push-7{position:relative;left:58.3333333333%}#spectacle .small-pull-7{position:relative;left:-58.3333333333%}#spectacle .small-offset-6{margin-left:50%}#spectacle .small-8{width:66.6666666667%}#spectacle .small-push-8{position:relative;left:66.6666666667%}#spectacle .small-pull-8{position:relative;left:-66.6666666667%}#spectacle .small-offset-7{margin-left:58.3333333333%}#spectacle .small-9{width:75%}#spectacle .small-push-9{position:relative;left:75%}#spectacle .small-pull-9{position:relative;left:-75%}#spectacle .small-offset-8{margin-left:66.6666666667%}#spectacle .small-10{width:83.3333333333%}#spectacle .small-push-10{position:relative;left:83.3333333333%}#spectacle .small-pull-10{position:relative;left:-83.3333333333%}#spectacle .small-offset-9{margin-left:75%}#spectacle .small-11{width:91.6666666667%}#spectacle .small-push-11{position:relative;left:91.6666666667%}#spectacle .small-pull-11{position:relative;left:-91.6666666667%}#spectacle .small-offset-10{margin-left:83.3333333333%}#spectacle .small-12{width:100%}#spectacle .small-offset-11{margin-left:91.6666666667%}#spectacle .small-up-1>.column,#spectacle .small-up-1>.columns,#spectacle article .prop-row .small-up-1>.prop-name,#spectacle article .prop-row .small-up-1>.prop-value,#spectacle article .small-up-1>.doc-copy,#spectacle article .small-up-1>.doc-examples{float:left;width:100%}#spectacle .small-up-1>.column:nth-of-type(1n),#spectacle .small-up-1>.columns:nth-of-type(1n),#spectacle article .prop-row .small-up-1>.prop-name:nth-of-type(1n),#spectacle article .prop-row .small-up-1>.prop-value:nth-of-type(1n),#spectacle article .small-up-1>.doc-copy:nth-of-type(1n),#spectacle article .small-up-1>.doc-examples:nth-of-type(1n){clear:none}#spectacle .small-up-1>.column:nth-of-type(1n+1),#spectacle .small-up-1>.columns:nth-of-type(1n+1),#spectacle article .prop-row .small-up-1>.prop-name:nth-of-type(1n+1),#spectacle article .prop-row .small-up-1>.prop-value:nth-of-type(1n+1),#spectacle article .small-up-1>.doc-copy:nth-of-type(1n+1),#spectacle article .small-up-1>.doc-examples:nth-of-type(1n+1){clear:both}#spectacle .small-up-1>.column:last-child,#spectacle .small-up-1>.columns:last-child,#spectacle article .prop-row .small-up-1>.prop-name:last-child,#spectacle article .prop-row .small-up-1>.prop-value:last-child,#spectacle article .small-up-1>.doc-copy:last-child,#spectacle article .small-up-1>.doc-examples:last-child{float:left}#spectacle .small-up-2>.column,#spectacle .small-up-2>.columns,#spectacle article .prop-row .small-up-2>.prop-name,#spectacle article .prop-row .small-up-2>.prop-value,#spectacle article .small-up-2>.doc-copy,#spectacle article .small-up-2>.doc-examples{float:left;width:50%}#spectacle .small-up-2>.column:nth-of-type(1n),#spectacle .small-up-2>.columns:nth-of-type(1n),#spectacle article .prop-row .small-up-2>.prop-name:nth-of-type(1n),#spectacle article .prop-row .small-up-2>.prop-value:nth-of-type(1n),#spectacle article .small-up-2>.doc-copy:nth-of-type(1n),#spectacle article .small-up-2>.doc-examples:nth-of-type(1n){clear:none}#spectacle .small-up-2>.column:nth-of-type(2n+1),#spectacle .small-up-2>.columns:nth-of-type(2n+1),#spectacle article .prop-row .small-up-2>.prop-name:nth-of-type(2n+1),#spectacle article .prop-row .small-up-2>.prop-value:nth-of-type(2n+1),#spectacle article .small-up-2>.doc-copy:nth-of-type(2n+1),#spectacle article .small-up-2>.doc-examples:nth-of-type(2n+1){clear:both}#spectacle .small-up-2>.column:last-child,#spectacle .small-up-2>.columns:last-child,#spectacle article .prop-row .small-up-2>.prop-name:last-child,#spectacle article .prop-row .small-up-2>.prop-value:last-child,#spectacle article .small-up-2>.doc-copy:last-child,#spectacle article .small-up-2>.doc-examples:last-child{float:left}#spectacle .small-up-3>.column,#spectacle .small-up-3>.columns,#spectacle article .prop-row .small-up-3>.prop-name,#spectacle article .prop-row .small-up-3>.prop-value,#spectacle article .small-up-3>.doc-copy,#spectacle article .small-up-3>.doc-examples{float:left;width:33.3333333333%}#spectacle .small-up-3>.column:nth-of-type(1n),#spectacle .small-up-3>.columns:nth-of-type(1n),#spectacle article .prop-row .small-up-3>.prop-name:nth-of-type(1n),#spectacle article .prop-row .small-up-3>.prop-value:nth-of-type(1n),#spectacle article .small-up-3>.doc-copy:nth-of-type(1n),#spectacle article .small-up-3>.doc-examples:nth-of-type(1n){clear:none}#spectacle .small-up-3>.column:nth-of-type(3n+1),#spectacle .small-up-3>.columns:nth-of-type(3n+1),#spectacle article .prop-row .small-up-3>.prop-name:nth-of-type(3n+1),#spectacle article .prop-row .small-up-3>.prop-value:nth-of-type(3n+1),#spectacle article .small-up-3>.doc-copy:nth-of-type(3n+1),#spectacle article .small-up-3>.doc-examples:nth-of-type(3n+1){clear:both}#spectacle .small-up-3>.column:last-child,#spectacle .small-up-3>.columns:last-child,#spectacle article .prop-row .small-up-3>.prop-name:last-child,#spectacle article .prop-row .small-up-3>.prop-value:last-child,#spectacle article .small-up-3>.doc-copy:last-child,#spectacle article .small-up-3>.doc-examples:last-child{float:left}#spectacle .small-up-4>.column,#spectacle .small-up-4>.columns,#spectacle article .prop-row .small-up-4>.prop-name,#spectacle article .prop-row .small-up-4>.prop-value,#spectacle article .small-up-4>.doc-copy,#spectacle article .small-up-4>.doc-examples{float:left;width:25%}#spectacle .small-up-4>.column:nth-of-type(1n),#spectacle .small-up-4>.columns:nth-of-type(1n),#spectacle article .prop-row .small-up-4>.prop-name:nth-of-type(1n),#spectacle article .prop-row .small-up-4>.prop-value:nth-of-type(1n),#spectacle article .small-up-4>.doc-copy:nth-of-type(1n),#spectacle article .small-up-4>.doc-examples:nth-of-type(1n){clear:none}#spectacle .small-up-4>.column:nth-of-type(4n+1),#spectacle .small-up-4>.columns:nth-of-type(4n+1),#spectacle article .prop-row .small-up-4>.prop-name:nth-of-type(4n+1),#spectacle article .prop-row .small-up-4>.prop-value:nth-of-type(4n+1),#spectacle article .small-up-4>.doc-copy:nth-of-type(4n+1),#spectacle article .small-up-4>.doc-examples:nth-of-type(4n+1){clear:both}#spectacle .small-up-4>.column:last-child,#spectacle .small-up-4>.columns:last-child,#spectacle article .prop-row .small-up-4>.prop-name:last-child,#spectacle article .prop-row .small-up-4>.prop-value:last-child,#spectacle article .small-up-4>.doc-copy:last-child,#spectacle article .small-up-4>.doc-examples:last-child{float:left}#spectacle .small-up-5>.column,#spectacle .small-up-5>.columns,#spectacle article .prop-row .small-up-5>.prop-name,#spectacle article .prop-row .small-up-5>.prop-value,#spectacle article .small-up-5>.doc-copy,#spectacle article .small-up-5>.doc-examples{float:left;width:20%}#spectacle .small-up-5>.column:nth-of-type(1n),#spectacle .small-up-5>.columns:nth-of-type(1n),#spectacle article .prop-row .small-up-5>.prop-name:nth-of-type(1n),#spectacle article .prop-row .small-up-5>.prop-value:nth-of-type(1n),#spectacle article .small-up-5>.doc-copy:nth-of-type(1n),#spectacle article .small-up-5>.doc-examples:nth-of-type(1n){clear:none}#spectacle .small-up-5>.column:nth-of-type(5n+1),#spectacle .small-up-5>.columns:nth-of-type(5n+1),#spectacle article .prop-row .small-up-5>.prop-name:nth-of-type(5n+1),#spectacle article .prop-row .small-up-5>.prop-value:nth-of-type(5n+1),#spectacle article .small-up-5>.doc-copy:nth-of-type(5n+1),#spectacle article .small-up-5>.doc-examples:nth-of-type(5n+1){clear:both}#spectacle .small-up-5>.column:last-child,#spectacle .small-up-5>.columns:last-child,#spectacle article .prop-row .small-up-5>.prop-name:last-child,#spectacle article .prop-row .small-up-5>.prop-value:last-child,#spectacle article .small-up-5>.doc-copy:last-child,#spectacle article .small-up-5>.doc-examples:last-child{float:left}#spectacle .small-up-6>.column,#spectacle .small-up-6>.columns,#spectacle article .prop-row .small-up-6>.prop-name,#spectacle article .prop-row .small-up-6>.prop-value,#spectacle article .small-up-6>.doc-copy,#spectacle article .small-up-6>.doc-examples{float:left;width:16.6666666667%}#spectacle .small-up-6>.column:nth-of-type(1n),#spectacle .small-up-6>.columns:nth-of-type(1n),#spectacle article .prop-row .small-up-6>.prop-name:nth-of-type(1n),#spectacle article .prop-row .small-up-6>.prop-value:nth-of-type(1n),#spectacle article .small-up-6>.doc-copy:nth-of-type(1n),#spectacle article .small-up-6>.doc-examples:nth-of-type(1n){clear:none}#spectacle .small-up-6>.column:nth-of-type(6n+1),#spectacle .small-up-6>.columns:nth-of-type(6n+1),#spectacle article .prop-row .small-up-6>.prop-name:nth-of-type(6n+1),#spectacle article .prop-row .small-up-6>.prop-value:nth-of-type(6n+1),#spectacle article .small-up-6>.doc-copy:nth-of-type(6n+1),#spectacle article .small-up-6>.doc-examples:nth-of-type(6n+1){clear:both}#spectacle .small-up-6>.column:last-child,#spectacle .small-up-6>.columns:last-child,#spectacle article .prop-row .small-up-6>.prop-name:last-child,#spectacle article .prop-row .small-up-6>.prop-value:last-child,#spectacle article .small-up-6>.doc-copy:last-child,#spectacle article .small-up-6>.doc-examples:last-child{float:left}#spectacle .small-up-7>.column,#spectacle .small-up-7>.columns,#spectacle article .prop-row .small-up-7>.prop-name,#spectacle article .prop-row .small-up-7>.prop-value,#spectacle article .small-up-7>.doc-copy,#spectacle article .small-up-7>.doc-examples{float:left;width:14.2857142857%}#spectacle .small-up-7>.column:nth-of-type(1n),#spectacle .small-up-7>.columns:nth-of-type(1n),#spectacle article .prop-row .small-up-7>.prop-name:nth-of-type(1n),#spectacle article .prop-row .small-up-7>.prop-value:nth-of-type(1n),#spectacle article .small-up-7>.doc-copy:nth-of-type(1n),#spectacle article .small-up-7>.doc-examples:nth-of-type(1n){clear:none}#spectacle .small-up-7>.column:nth-of-type(7n+1),#spectacle .small-up-7>.columns:nth-of-type(7n+1),#spectacle article .prop-row .small-up-7>.prop-name:nth-of-type(7n+1),#spectacle article .prop-row .small-up-7>.prop-value:nth-of-type(7n+1),#spectacle article .small-up-7>.doc-copy:nth-of-type(7n+1),#spectacle article .small-up-7>.doc-examples:nth-of-type(7n+1){clear:both}#spectacle .small-up-7>.column:last-child,#spectacle .small-up-7>.columns:last-child,#spectacle article .prop-row .small-up-7>.prop-name:last-child,#spectacle article .prop-row .small-up-7>.prop-value:last-child,#spectacle article .small-up-7>.doc-copy:last-child,#spectacle article .small-up-7>.doc-examples:last-child{float:left}#spectacle .small-up-8>.column,#spectacle .small-up-8>.columns,#spectacle article .prop-row .small-up-8>.prop-name,#spectacle article .prop-row .small-up-8>.prop-value,#spectacle article .small-up-8>.doc-copy,#spectacle article .small-up-8>.doc-examples{float:left;width:12.5%}#spectacle .small-up-8>.column:nth-of-type(1n),#spectacle .small-up-8>.columns:nth-of-type(1n),#spectacle article .prop-row .small-up-8>.prop-name:nth-of-type(1n),#spectacle article .prop-row .small-up-8>.prop-value:nth-of-type(1n),#spectacle article .small-up-8>.doc-copy:nth-of-type(1n),#spectacle article .small-up-8>.doc-examples:nth-of-type(1n){clear:none}#spectacle .small-up-8>.column:nth-of-type(8n+1),#spectacle .small-up-8>.columns:nth-of-type(8n+1),#spectacle article .prop-row .small-up-8>.prop-name:nth-of-type(8n+1),#spectacle article .prop-row .small-up-8>.prop-value:nth-of-type(8n+1),#spectacle article .small-up-8>.doc-copy:nth-of-type(8n+1),#spectacle article .small-up-8>.doc-examples:nth-of-type(8n+1){clear:both}#spectacle .small-up-8>.column:last-child,#spectacle .small-up-8>.columns:last-child,#spectacle article .prop-row .small-up-8>.prop-name:last-child,#spectacle article .prop-row .small-up-8>.prop-value:last-child,#spectacle article .small-up-8>.doc-copy:last-child,#spectacle article .small-up-8>.doc-examples:last-child{float:left}#spectacle .small-collapse>.column,#spectacle .small-collapse>.columns,#spectacle article .prop-row .small-collapse>.prop-name,#spectacle article .prop-row .small-collapse>.prop-value,#spectacle article .small-collapse>.doc-copy,#spectacle article .small-collapse>.doc-examples{padding-right:0;padding-left:0}#spectacle .small-collapse .row,#spectacle .small-collapse article .doc-row,#spectacle .small-collapse article .prop-row,#spectacle article .small-collapse .doc-row,#spectacle article .small-collapse .prop-row{margin-right:0;margin-left:0}#spectacle .expanded.row .small-collapse.row,#spectacle .expanded.row article .small-collapse.doc-row,#spectacle .expanded.row article .small-collapse.prop-row,#spectacle article .expanded.doc-row .small-collapse.doc-row,#spectacle article .expanded.doc-row .small-collapse.prop-row,#spectacle article .expanded.doc-row .small-collapse.row,#spectacle article .expanded.prop-row .small-collapse.doc-row,#spectacle article .expanded.prop-row .small-collapse.prop-row,#spectacle article .expanded.prop-row .small-collapse.row,#spectacle article .expanded.row .small-collapse.doc-row,#spectacle article .expanded.row .small-collapse.prop-row{margin-right:0;margin-left:0}#spectacle .small-uncollapse>.column,#spectacle .small-uncollapse>.columns,#spectacle article .prop-row .small-uncollapse>.prop-name,#spectacle article .prop-row .small-uncollapse>.prop-value,#spectacle article .small-uncollapse>.doc-copy,#spectacle article .small-uncollapse>.doc-examples{padding-right:.6578947368rem;padding-left:.6578947368rem}#spectacle .small-centered{margin-right:auto;margin-left:auto}#spectacle .small-centered,#spectacle .small-centered:last-child:not(:first-child){float:none;clear:both}#spectacle .small-pull-0,#spectacle .small-push-0,#spectacle .small-uncentered{position:static;margin-right:0;margin-left:0}#spectacle .small-pull-0,#spectacle .small-pull-0:last-child:not(:first-child),#spectacle .small-push-0,#spectacle .small-push-0:last-child:not(:first-child),#spectacle .small-uncentered,#spectacle .small-uncentered:last-child:not(:first-child){float:left;clear:none}#spectacle .small-pull-0:last-child:not(:first-child),#spectacle .small-push-0:last-child:not(:first-child),#spectacle .small-uncentered:last-child:not(:first-child){float:right}@media print,screen and (min-width:40em){#spectacle .medium-1{width:8.3333333333%}#spectacle .medium-push-1{position:relative;left:8.3333333333%}#spectacle .medium-pull-1{position:relative;left:-8.3333333333%}#spectacle .medium-offset-0{margin-left:0}#spectacle .medium-2{width:16.6666666667%}#spectacle .medium-push-2{position:relative;left:16.6666666667%}#spectacle .medium-pull-2{position:relative;left:-16.6666666667%}#spectacle .medium-offset-1{margin-left:8.3333333333%}#spectacle .medium-3{width:25%}#spectacle .medium-push-3{position:relative;left:25%}#spectacle .medium-pull-3{position:relative;left:-25%}#spectacle .medium-offset-2{margin-left:16.6666666667%}#spectacle .medium-4{width:33.3333333333%}#spectacle .medium-push-4{position:relative;left:33.3333333333%}#spectacle .medium-pull-4{position:relative;left:-33.3333333333%}#spectacle .medium-offset-3{margin-left:25%}#spectacle .medium-5{width:41.6666666667%}#spectacle .medium-push-5{position:relative;left:41.6666666667%}#spectacle .medium-pull-5{position:relative;left:-41.6666666667%}#spectacle .medium-offset-4{margin-left:33.3333333333%}#spectacle .medium-6{width:50%}#spectacle .medium-push-6{position:relative;left:50%}#spectacle .medium-pull-6{position:relative;left:-50%}#spectacle .medium-offset-5{margin-left:41.6666666667%}#spectacle .medium-7{width:58.3333333333%}#spectacle .medium-push-7{position:relative;left:58.3333333333%}#spectacle .medium-pull-7{position:relative;left:-58.3333333333%}#spectacle .medium-offset-6{margin-left:50%}#spectacle .medium-8{width:66.6666666667%}#spectacle .medium-push-8{position:relative;left:66.6666666667%}#spectacle .medium-pull-8{position:relative;left:-66.6666666667%}#spectacle .medium-offset-7{margin-left:58.3333333333%}#spectacle .medium-9{width:75%}#spectacle .medium-push-9{position:relative;left:75%}#spectacle .medium-pull-9{position:relative;left:-75%}#spectacle .medium-offset-8{margin-left:66.6666666667%}#spectacle .medium-10{width:83.3333333333%}#spectacle .medium-push-10{position:relative;left:83.3333333333%}#spectacle .medium-pull-10{position:relative;left:-83.3333333333%}#spectacle .medium-offset-9{margin-left:75%}#spectacle .medium-11{width:91.6666666667%}#spectacle .medium-push-11{position:relative;left:91.6666666667%}#spectacle .medium-pull-11{position:relative;left:-91.6666666667%}#spectacle .medium-offset-10{margin-left:83.3333333333%}#spectacle .medium-12{width:100%}#spectacle .medium-offset-11{margin-left:91.6666666667%}#spectacle .medium-up-1>.column,#spectacle .medium-up-1>.columns,#spectacle article .medium-up-1>.doc-copy,#spectacle article .medium-up-1>.doc-examples,#spectacle article .prop-row .medium-up-1>.prop-name,#spectacle article .prop-row .medium-up-1>.prop-value{float:left;width:100%}#spectacle .medium-up-1>.column:nth-of-type(1n),#spectacle .medium-up-1>.columns:nth-of-type(1n),#spectacle article .medium-up-1>.doc-copy:nth-of-type(1n),#spectacle article .medium-up-1>.doc-examples:nth-of-type(1n),#spectacle article .prop-row .medium-up-1>.prop-name:nth-of-type(1n),#spectacle article .prop-row .medium-up-1>.prop-value:nth-of-type(1n){clear:none}#spectacle .medium-up-1>.column:nth-of-type(1n+1),#spectacle .medium-up-1>.columns:nth-of-type(1n+1),#spectacle article .medium-up-1>.doc-copy:nth-of-type(1n+1),#spectacle article .medium-up-1>.doc-examples:nth-of-type(1n+1),#spectacle article .prop-row .medium-up-1>.prop-name:nth-of-type(1n+1),#spectacle article .prop-row .medium-up-1>.prop-value:nth-of-type(1n+1){clear:both}#spectacle .medium-up-1>.column:last-child,#spectacle .medium-up-1>.columns:last-child,#spectacle article .medium-up-1>.doc-copy:last-child,#spectacle article .medium-up-1>.doc-examples:last-child,#spectacle article .prop-row .medium-up-1>.prop-name:last-child,#spectacle article .prop-row .medium-up-1>.prop-value:last-child{float:left}#spectacle .medium-up-2>.column,#spectacle .medium-up-2>.columns,#spectacle article .medium-up-2>.doc-copy,#spectacle article .medium-up-2>.doc-examples,#spectacle article .prop-row .medium-up-2>.prop-name,#spectacle article .prop-row .medium-up-2>.prop-value{float:left;width:50%}#spectacle .medium-up-2>.column:nth-of-type(1n),#spectacle .medium-up-2>.columns:nth-of-type(1n),#spectacle article .medium-up-2>.doc-copy:nth-of-type(1n),#spectacle article .medium-up-2>.doc-examples:nth-of-type(1n),#spectacle article .prop-row .medium-up-2>.prop-name:nth-of-type(1n),#spectacle article .prop-row .medium-up-2>.prop-value:nth-of-type(1n){clear:none}#spectacle .medium-up-2>.column:nth-of-type(2n+1),#spectacle .medium-up-2>.columns:nth-of-type(2n+1),#spectacle article .medium-up-2>.doc-copy:nth-of-type(2n+1),#spectacle article .medium-up-2>.doc-examples:nth-of-type(2n+1),#spectacle article .prop-row .medium-up-2>.prop-name:nth-of-type(2n+1),#spectacle article .prop-row .medium-up-2>.prop-value:nth-of-type(2n+1){clear:both}#spectacle .medium-up-2>.column:last-child,#spectacle .medium-up-2>.columns:last-child,#spectacle article .medium-up-2>.doc-copy:last-child,#spectacle article .medium-up-2>.doc-examples:last-child,#spectacle article .prop-row .medium-up-2>.prop-name:last-child,#spectacle article .prop-row .medium-up-2>.prop-value:last-child{float:left}#spectacle .medium-up-3>.column,#spectacle .medium-up-3>.columns,#spectacle article .medium-up-3>.doc-copy,#spectacle article .medium-up-3>.doc-examples,#spectacle article .prop-row .medium-up-3>.prop-name,#spectacle article .prop-row .medium-up-3>.prop-value{float:left;width:33.3333333333%}#spectacle .medium-up-3>.column:nth-of-type(1n),#spectacle .medium-up-3>.columns:nth-of-type(1n),#spectacle article .medium-up-3>.doc-copy:nth-of-type(1n),#spectacle article .medium-up-3>.doc-examples:nth-of-type(1n),#spectacle article .prop-row .medium-up-3>.prop-name:nth-of-type(1n),#spectacle article .prop-row .medium-up-3>.prop-value:nth-of-type(1n){clear:none}#spectacle .medium-up-3>.column:nth-of-type(3n+1),#spectacle .medium-up-3>.columns:nth-of-type(3n+1),#spectacle article .medium-up-3>.doc-copy:nth-of-type(3n+1),#spectacle article .medium-up-3>.doc-examples:nth-of-type(3n+1),#spectacle article .prop-row .medium-up-3>.prop-name:nth-of-type(3n+1),#spectacle article .prop-row .medium-up-3>.prop-value:nth-of-type(3n+1){clear:both}#spectacle .medium-up-3>.column:last-child,#spectacle .medium-up-3>.columns:last-child,#spectacle article .medium-up-3>.doc-copy:last-child,#spectacle article .medium-up-3>.doc-examples:last-child,#spectacle article .prop-row .medium-up-3>.prop-name:last-child,#spectacle article .prop-row .medium-up-3>.prop-value:last-child{float:left}#spectacle .medium-up-4>.column,#spectacle .medium-up-4>.columns,#spectacle article .medium-up-4>.doc-copy,#spectacle article .medium-up-4>.doc-examples,#spectacle article .prop-row .medium-up-4>.prop-name,#spectacle article .prop-row .medium-up-4>.prop-value{float:left;width:25%}#spectacle .medium-up-4>.column:nth-of-type(1n),#spectacle .medium-up-4>.columns:nth-of-type(1n),#spectacle article .medium-up-4>.doc-copy:nth-of-type(1n),#spectacle article .medium-up-4>.doc-examples:nth-of-type(1n),#spectacle article .prop-row .medium-up-4>.prop-name:nth-of-type(1n),#spectacle article .prop-row .medium-up-4>.prop-value:nth-of-type(1n){clear:none}#spectacle .medium-up-4>.column:nth-of-type(4n+1),#spectacle .medium-up-4>.columns:nth-of-type(4n+1),#spectacle article .medium-up-4>.doc-copy:nth-of-type(4n+1),#spectacle article .medium-up-4>.doc-examples:nth-of-type(4n+1),#spectacle article .prop-row .medium-up-4>.prop-name:nth-of-type(4n+1),#spectacle article .prop-row .medium-up-4>.prop-value:nth-of-type(4n+1){clear:both}#spectacle .medium-up-4>.column:last-child,#spectacle .medium-up-4>.columns:last-child,#spectacle article .medium-up-4>.doc-copy:last-child,#spectacle article .medium-up-4>.doc-examples:last-child,#spectacle article .prop-row .medium-up-4>.prop-name:last-child,#spectacle article .prop-row .medium-up-4>.prop-value:last-child{float:left}#spectacle .medium-up-5>.column,#spectacle .medium-up-5>.columns,#spectacle article .medium-up-5>.doc-copy,#spectacle article .medium-up-5>.doc-examples,#spectacle article .prop-row .medium-up-5>.prop-name,#spectacle article .prop-row .medium-up-5>.prop-value{float:left;width:20%}#spectacle .medium-up-5>.column:nth-of-type(1n),#spectacle .medium-up-5>.columns:nth-of-type(1n),#spectacle article .medium-up-5>.doc-copy:nth-of-type(1n),#spectacle article .medium-up-5>.doc-examples:nth-of-type(1n),#spectacle article .prop-row .medium-up-5>.prop-name:nth-of-type(1n),#spectacle article .prop-row .medium-up-5>.prop-value:nth-of-type(1n){clear:none}#spectacle .medium-up-5>.column:nth-of-type(5n+1),#spectacle .medium-up-5>.columns:nth-of-type(5n+1),#spectacle article .medium-up-5>.doc-copy:nth-of-type(5n+1),#spectacle article .medium-up-5>.doc-examples:nth-of-type(5n+1),#spectacle article .prop-row .medium-up-5>.prop-name:nth-of-type(5n+1),#spectacle article .prop-row .medium-up-5>.prop-value:nth-of-type(5n+1){clear:both}#spectacle .medium-up-5>.column:last-child,#spectacle .medium-up-5>.columns:last-child,#spectacle article .medium-up-5>.doc-copy:last-child,#spectacle article .medium-up-5>.doc-examples:last-child,#spectacle article .prop-row .medium-up-5>.prop-name:last-child,#spectacle article .prop-row .medium-up-5>.prop-value:last-child{float:left}#spectacle .medium-up-6>.column,#spectacle .medium-up-6>.columns,#spectacle article .medium-up-6>.doc-copy,#spectacle article .medium-up-6>.doc-examples,#spectacle article .prop-row .medium-up-6>.prop-name,#spectacle article .prop-row .medium-up-6>.prop-value{float:left;width:16.6666666667%}#spectacle .medium-up-6>.column:nth-of-type(1n),#spectacle .medium-up-6>.columns:nth-of-type(1n),#spectacle article .medium-up-6>.doc-copy:nth-of-type(1n),#spectacle article .medium-up-6>.doc-examples:nth-of-type(1n),#spectacle article .prop-row .medium-up-6>.prop-name:nth-of-type(1n),#spectacle article .prop-row .medium-up-6>.prop-value:nth-of-type(1n){clear:none}#spectacle .medium-up-6>.column:nth-of-type(6n+1),#spectacle .medium-up-6>.columns:nth-of-type(6n+1),#spectacle article .medium-up-6>.doc-copy:nth-of-type(6n+1),#spectacle article .medium-up-6>.doc-examples:nth-of-type(6n+1),#spectacle article .prop-row .medium-up-6>.prop-name:nth-of-type(6n+1),#spectacle article .prop-row .medium-up-6>.prop-value:nth-of-type(6n+1){clear:both}#spectacle .medium-up-6>.column:last-child,#spectacle .medium-up-6>.columns:last-child,#spectacle article .medium-up-6>.doc-copy:last-child,#spectacle article .medium-up-6>.doc-examples:last-child,#spectacle article .prop-row .medium-up-6>.prop-name:last-child,#spectacle article .prop-row .medium-up-6>.prop-value:last-child{float:left}#spectacle .medium-up-7>.column,#spectacle .medium-up-7>.columns,#spectacle article .medium-up-7>.doc-copy,#spectacle article .medium-up-7>.doc-examples,#spectacle article .prop-row .medium-up-7>.prop-name,#spectacle article .prop-row .medium-up-7>.prop-value{float:left;width:14.2857142857%}#spectacle .medium-up-7>.column:nth-of-type(1n),#spectacle .medium-up-7>.columns:nth-of-type(1n),#spectacle article .medium-up-7>.doc-copy:nth-of-type(1n),#spectacle article .medium-up-7>.doc-examples:nth-of-type(1n),#spectacle article .prop-row .medium-up-7>.prop-name:nth-of-type(1n),#spectacle article .prop-row .medium-up-7>.prop-value:nth-of-type(1n){clear:none}#spectacle .medium-up-7>.column:nth-of-type(7n+1),#spectacle .medium-up-7>.columns:nth-of-type(7n+1),#spectacle article .medium-up-7>.doc-copy:nth-of-type(7n+1),#spectacle article .medium-up-7>.doc-examples:nth-of-type(7n+1),#spectacle article .prop-row .medium-up-7>.prop-name:nth-of-type(7n+1),#spectacle article .prop-row .medium-up-7>.prop-value:nth-of-type(7n+1){clear:both}#spectacle .medium-up-7>.column:last-child,#spectacle .medium-up-7>.columns:last-child,#spectacle article .medium-up-7>.doc-copy:last-child,#spectacle article .medium-up-7>.doc-examples:last-child,#spectacle article .prop-row .medium-up-7>.prop-name:last-child,#spectacle article .prop-row .medium-up-7>.prop-value:last-child{float:left}#spectacle .medium-up-8>.column,#spectacle .medium-up-8>.columns,#spectacle article .medium-up-8>.doc-copy,#spectacle article .medium-up-8>.doc-examples,#spectacle article .prop-row .medium-up-8>.prop-name,#spectacle article .prop-row .medium-up-8>.prop-value{float:left;width:12.5%}#spectacle .medium-up-8>.column:nth-of-type(1n),#spectacle .medium-up-8>.columns:nth-of-type(1n),#spectacle article .medium-up-8>.doc-copy:nth-of-type(1n),#spectacle article .medium-up-8>.doc-examples:nth-of-type(1n),#spectacle article .prop-row .medium-up-8>.prop-name:nth-of-type(1n),#spectacle article .prop-row .medium-up-8>.prop-value:nth-of-type(1n){clear:none}#spectacle .medium-up-8>.column:nth-of-type(8n+1),#spectacle .medium-up-8>.columns:nth-of-type(8n+1),#spectacle article .medium-up-8>.doc-copy:nth-of-type(8n+1),#spectacle article .medium-up-8>.doc-examples:nth-of-type(8n+1),#spectacle article .prop-row .medium-up-8>.prop-name:nth-of-type(8n+1),#spectacle article .prop-row .medium-up-8>.prop-value:nth-of-type(8n+1){clear:both}#spectacle .medium-up-8>.column:last-child,#spectacle .medium-up-8>.columns:last-child,#spectacle article .medium-up-8>.doc-copy:last-child,#spectacle article .medium-up-8>.doc-examples:last-child,#spectacle article .prop-row .medium-up-8>.prop-name:last-child,#spectacle article .prop-row .medium-up-8>.prop-value:last-child{float:left}#spectacle .medium-collapse>.column,#spectacle .medium-collapse>.columns,#spectacle article .medium-collapse>.doc-copy,#spectacle article .medium-collapse>.doc-examples,#spectacle article .prop-row .medium-collapse>.prop-name,#spectacle article .prop-row .medium-collapse>.prop-value{padding-right:0;padding-left:0}#spectacle .medium-collapse .row,#spectacle .medium-collapse article .doc-row,#spectacle .medium-collapse article .prop-row,#spectacle article .medium-collapse .doc-row,#spectacle article .medium-collapse .prop-row{margin-right:0;margin-left:0}#spectacle .expanded.row .medium-collapse.row,#spectacle .expanded.row article .medium-collapse.doc-row,#spectacle .expanded.row article .medium-collapse.prop-row,#spectacle article .expanded.doc-row .medium-collapse.doc-row,#spectacle article .expanded.doc-row .medium-collapse.prop-row,#spectacle article .expanded.doc-row .medium-collapse.row,#spectacle article .expanded.prop-row .medium-collapse.doc-row,#spectacle article .expanded.prop-row .medium-collapse.prop-row,#spectacle article .expanded.prop-row .medium-collapse.row,#spectacle article .expanded.row .medium-collapse.doc-row,#spectacle article .expanded.row .medium-collapse.prop-row{margin-right:0;margin-left:0}#spectacle .medium-uncollapse>.column,#spectacle .medium-uncollapse>.columns,#spectacle article .medium-uncollapse>.doc-copy,#spectacle article .medium-uncollapse>.doc-examples,#spectacle article .prop-row .medium-uncollapse>.prop-name,#spectacle article .prop-row .medium-uncollapse>.prop-value{padding-right:.9868421053rem;padding-left:.9868421053rem}#spectacle .medium-centered{margin-right:auto;margin-left:auto}#spectacle .medium-centered,#spectacle .medium-centered:last-child:not(:first-child){float:none;clear:both}#spectacle .medium-pull-0,#spectacle .medium-push-0,#spectacle .medium-uncentered{position:static;margin-right:0;margin-left:0}#spectacle .medium-pull-0,#spectacle .medium-pull-0:last-child:not(:first-child),#spectacle .medium-push-0,#spectacle .medium-push-0:last-child:not(:first-child),#spectacle .medium-uncentered,#spectacle .medium-uncentered:last-child:not(:first-child){float:left;clear:none}#spectacle .medium-pull-0:last-child:not(:first-child),#spectacle .medium-push-0:last-child:not(:first-child),#spectacle .medium-uncentered:last-child:not(:first-child){float:right}}@media print,screen and (min-width:64em){#spectacle .large-1{width:8.3333333333%}#spectacle .large-push-1{position:relative;left:8.3333333333%}#spectacle .large-pull-1{position:relative;left:-8.3333333333%}#spectacle .large-offset-0{margin-left:0}#spectacle .large-2{width:16.6666666667%}#spectacle .large-push-2{position:relative;left:16.6666666667%}#spectacle .large-pull-2{position:relative;left:-16.6666666667%}#spectacle .large-offset-1{margin-left:8.3333333333%}#spectacle .large-3{width:25%}#spectacle .large-push-3{position:relative;left:25%}#spectacle .large-pull-3{position:relative;left:-25%}#spectacle .large-offset-2{margin-left:16.6666666667%}#spectacle .large-4{width:33.3333333333%}#spectacle .large-push-4{position:relative;left:33.3333333333%}#spectacle .large-pull-4{position:relative;left:-33.3333333333%}#spectacle .large-offset-3{margin-left:25%}#spectacle .large-5{width:41.6666666667%}#spectacle .large-push-5{position:relative;left:41.6666666667%}#spectacle .large-pull-5{position:relative;left:-41.6666666667%}#spectacle .large-offset-4{margin-left:33.3333333333%}#spectacle .doc-content,#spectacle .large-6,#spectacle article .doc-copy,#spectacle article .doc-examples,#spectacle article .panel>h2,#spectacle article .panel>h3,#spectacle article h1.doc-title,#spectacle article h5.doc-intro-item,#spectacle article>h1,#spectacle article>h2{width:50%}#spectacle .large-push-6{position:relative;left:50%}#spectacle .large-pull-6{position:relative;left:-50%}#spectacle .large-offset-5{margin-left:41.6666666667%}#spectacle .large-7{width:58.3333333333%}#spectacle .large-push-7{position:relative;left:58.3333333333%}#spectacle .large-pull-7{position:relative;left:-58.3333333333%}#spectacle .large-offset-6{margin-left:50%}#spectacle .large-8{width:66.6666666667%}#spectacle .large-push-8{position:relative;left:66.6666666667%}#spectacle .large-pull-8{position:relative;left:-66.6666666667%}#spectacle .large-offset-7{margin-left:58.3333333333%}#spectacle .large-9{width:75%}#spectacle .large-push-9{position:relative;left:75%}#spectacle .large-pull-9{position:relative;left:-75%}#spectacle .large-offset-8{margin-left:66.6666666667%}#spectacle .large-10{width:83.3333333333%}#spectacle .large-push-10{position:relative;left:83.3333333333%}#spectacle .large-pull-10{position:relative;left:-83.3333333333%}#spectacle .large-offset-9{margin-left:75%}#spectacle .large-11{width:91.6666666667%}#spectacle .large-push-11{position:relative;left:91.6666666667%}#spectacle .large-pull-11{position:relative;left:-91.6666666667%}#spectacle .large-offset-10{margin-left:83.3333333333%}#spectacle .large-12{width:100%}#spectacle .large-offset-11{margin-left:91.6666666667%}#spectacle .large-up-1>.column,#spectacle .large-up-1>.columns,#spectacle article .large-up-1>.doc-copy,#spectacle article .large-up-1>.doc-examples,#spectacle article .prop-row .large-up-1>.prop-name,#spectacle article .prop-row .large-up-1>.prop-value{float:left;width:100%}#spectacle .large-up-1>.column:nth-of-type(1n),#spectacle .large-up-1>.columns:nth-of-type(1n),#spectacle article .large-up-1>.doc-copy:nth-of-type(1n),#spectacle article .large-up-1>.doc-examples:nth-of-type(1n),#spectacle article .prop-row .large-up-1>.prop-name:nth-of-type(1n),#spectacle article .prop-row .large-up-1>.prop-value:nth-of-type(1n){clear:none}#spectacle .large-up-1>.column:nth-of-type(1n+1),#spectacle .large-up-1>.columns:nth-of-type(1n+1),#spectacle article .large-up-1>.doc-copy:nth-of-type(1n+1),#spectacle article .large-up-1>.doc-examples:nth-of-type(1n+1),#spectacle article .prop-row .large-up-1>.prop-name:nth-of-type(1n+1),#spectacle article .prop-row .large-up-1>.prop-value:nth-of-type(1n+1){clear:both}#spectacle .large-up-1>.column:last-child,#spectacle .large-up-1>.columns:last-child,#spectacle article .large-up-1>.doc-copy:last-child,#spectacle article .large-up-1>.doc-examples:last-child,#spectacle article .prop-row .large-up-1>.prop-name:last-child,#spectacle article .prop-row .large-up-1>.prop-value:last-child{float:left}#spectacle .large-up-2>.column,#spectacle .large-up-2>.columns,#spectacle article .large-up-2>.doc-copy,#spectacle article .large-up-2>.doc-examples,#spectacle article .prop-row .large-up-2>.prop-name,#spectacle article .prop-row .large-up-2>.prop-value{float:left;width:50%}#spectacle .large-up-2>.column:nth-of-type(1n),#spectacle .large-up-2>.columns:nth-of-type(1n),#spectacle article .large-up-2>.doc-copy:nth-of-type(1n),#spectacle article .large-up-2>.doc-examples:nth-of-type(1n),#spectacle article .prop-row .large-up-2>.prop-name:nth-of-type(1n),#spectacle article .prop-row .large-up-2>.prop-value:nth-of-type(1n){clear:none}#spectacle .large-up-2>.column:nth-of-type(2n+1),#spectacle .large-up-2>.columns:nth-of-type(2n+1),#spectacle article .large-up-2>.doc-copy:nth-of-type(2n+1),#spectacle article .large-up-2>.doc-examples:nth-of-type(2n+1),#spectacle article .prop-row .large-up-2>.prop-name:nth-of-type(2n+1),#spectacle article .prop-row .large-up-2>.prop-value:nth-of-type(2n+1){clear:both}#spectacle .large-up-2>.column:last-child,#spectacle .large-up-2>.columns:last-child,#spectacle article .large-up-2>.doc-copy:last-child,#spectacle article .large-up-2>.doc-examples:last-child,#spectacle article .prop-row .large-up-2>.prop-name:last-child,#spectacle article .prop-row .large-up-2>.prop-value:last-child{float:left}#spectacle .large-up-3>.column,#spectacle .large-up-3>.columns,#spectacle article .large-up-3>.doc-copy,#spectacle article .large-up-3>.doc-examples,#spectacle article .prop-row .large-up-3>.prop-name,#spectacle article .prop-row .large-up-3>.prop-value{float:left;width:33.3333333333%}#spectacle .large-up-3>.column:nth-of-type(1n),#spectacle .large-up-3>.columns:nth-of-type(1n),#spectacle article .large-up-3>.doc-copy:nth-of-type(1n),#spectacle article .large-up-3>.doc-examples:nth-of-type(1n),#spectacle article .prop-row .large-up-3>.prop-name:nth-of-type(1n),#spectacle article .prop-row .large-up-3>.prop-value:nth-of-type(1n){clear:none}#spectacle .large-up-3>.column:nth-of-type(3n+1),#spectacle .large-up-3>.columns:nth-of-type(3n+1),#spectacle article .large-up-3>.doc-copy:nth-of-type(3n+1),#spectacle article .large-up-3>.doc-examples:nth-of-type(3n+1),#spectacle article .prop-row .large-up-3>.prop-name:nth-of-type(3n+1),#spectacle article .prop-row .large-up-3>.prop-value:nth-of-type(3n+1){clear:both}#spectacle .large-up-3>.column:last-child,#spectacle .large-up-3>.columns:last-child,#spectacle article .large-up-3>.doc-copy:last-child,#spectacle article .large-up-3>.doc-examples:last-child,#spectacle article .prop-row .large-up-3>.prop-name:last-child,#spectacle article .prop-row .large-up-3>.prop-value:last-child{float:left}#spectacle .large-up-4>.column,#spectacle .large-up-4>.columns,#spectacle article .large-up-4>.doc-copy,#spectacle article .large-up-4>.doc-examples,#spectacle article .prop-row .large-up-4>.prop-name,#spectacle article .prop-row .large-up-4>.prop-value{float:left;width:25%}#spectacle .large-up-4>.column:nth-of-type(1n),#spectacle .large-up-4>.columns:nth-of-type(1n),#spectacle article .large-up-4>.doc-copy:nth-of-type(1n),#spectacle article .large-up-4>.doc-examples:nth-of-type(1n),#spectacle article .prop-row .large-up-4>.prop-name:nth-of-type(1n),#spectacle article .prop-row .large-up-4>.prop-value:nth-of-type(1n){clear:none}#spectacle .large-up-4>.column:nth-of-type(4n+1),#spectacle .large-up-4>.columns:nth-of-type(4n+1),#spectacle article .large-up-4>.doc-copy:nth-of-type(4n+1),#spectacle article .large-up-4>.doc-examples:nth-of-type(4n+1),#spectacle article .prop-row .large-up-4>.prop-name:nth-of-type(4n+1),#spectacle article .prop-row .large-up-4>.prop-value:nth-of-type(4n+1){clear:both}#spectacle .large-up-4>.column:last-child,#spectacle .large-up-4>.columns:last-child,#spectacle article .large-up-4>.doc-copy:last-child,#spectacle article .large-up-4>.doc-examples:last-child,#spectacle article .prop-row .large-up-4>.prop-name:last-child,#spectacle article .prop-row .large-up-4>.prop-value:last-child{float:left}#spectacle .large-up-5>.column,#spectacle .large-up-5>.columns,#spectacle article .large-up-5>.doc-copy,#spectacle article .large-up-5>.doc-examples,#spectacle article .prop-row .large-up-5>.prop-name,#spectacle article .prop-row .large-up-5>.prop-value{float:left;width:20%}#spectacle .large-up-5>.column:nth-of-type(1n),#spectacle .large-up-5>.columns:nth-of-type(1n),#spectacle article .large-up-5>.doc-copy:nth-of-type(1n),#spectacle article .large-up-5>.doc-examples:nth-of-type(1n),#spectacle article .prop-row .large-up-5>.prop-name:nth-of-type(1n),#spectacle article .prop-row .large-up-5>.prop-value:nth-of-type(1n){clear:none}#spectacle .large-up-5>.column:nth-of-type(5n+1),#spectacle .large-up-5>.columns:nth-of-type(5n+1),#spectacle article .large-up-5>.doc-copy:nth-of-type(5n+1),#spectacle article .large-up-5>.doc-examples:nth-of-type(5n+1),#spectacle article .prop-row .large-up-5>.prop-name:nth-of-type(5n+1),#spectacle article .prop-row .large-up-5>.prop-value:nth-of-type(5n+1){clear:both}#spectacle .large-up-5>.column:last-child,#spectacle .large-up-5>.columns:last-child,#spectacle article .large-up-5>.doc-copy:last-child,#spectacle article .large-up-5>.doc-examples:last-child,#spectacle article .prop-row .large-up-5>.prop-name:last-child,#spectacle article .prop-row .large-up-5>.prop-value:last-child{float:left}#spectacle .large-up-6>.column,#spectacle .large-up-6>.columns,#spectacle article .large-up-6>.doc-copy,#spectacle article .large-up-6>.doc-examples,#spectacle article .prop-row .large-up-6>.prop-name,#spectacle article .prop-row .large-up-6>.prop-value{float:left;width:16.6666666667%}#spectacle .large-up-6>.column:nth-of-type(1n),#spectacle .large-up-6>.columns:nth-of-type(1n),#spectacle article .large-up-6>.doc-copy:nth-of-type(1n),#spectacle article .large-up-6>.doc-examples:nth-of-type(1n),#spectacle article .prop-row .large-up-6>.prop-name:nth-of-type(1n),#spectacle article .prop-row .large-up-6>.prop-value:nth-of-type(1n){clear:none}#spectacle .large-up-6>.column:nth-of-type(6n+1),#spectacle .large-up-6>.columns:nth-of-type(6n+1),#spectacle article .large-up-6>.doc-copy:nth-of-type(6n+1),#spectacle article .large-up-6>.doc-examples:nth-of-type(6n+1),#spectacle article .prop-row .large-up-6>.prop-name:nth-of-type(6n+1),#spectacle article .prop-row .large-up-6>.prop-value:nth-of-type(6n+1){clear:both}#spectacle .large-up-6>.column:last-child,#spectacle .large-up-6>.columns:last-child,#spectacle article .large-up-6>.doc-copy:last-child,#spectacle article .large-up-6>.doc-examples:last-child,#spectacle article .prop-row .large-up-6>.prop-name:last-child,#spectacle article .prop-row .large-up-6>.prop-value:last-child{float:left}#spectacle .large-up-7>.column,#spectacle .large-up-7>.columns,#spectacle article .large-up-7>.doc-copy,#spectacle article .large-up-7>.doc-examples,#spectacle article .prop-row .large-up-7>.prop-name,#spectacle article .prop-row .large-up-7>.prop-value{float:left;width:14.2857142857%}#spectacle .large-up-7>.column:nth-of-type(1n),#spectacle .large-up-7>.columns:nth-of-type(1n),#spectacle article .large-up-7>.doc-copy:nth-of-type(1n),#spectacle article .large-up-7>.doc-examples:nth-of-type(1n),#spectacle article .prop-row .large-up-7>.prop-name:nth-of-type(1n),#spectacle article .prop-row .large-up-7>.prop-value:nth-of-type(1n){clear:none}#spectacle .large-up-7>.column:nth-of-type(7n+1),#spectacle .large-up-7>.columns:nth-of-type(7n+1),#spectacle article .large-up-7>.doc-copy:nth-of-type(7n+1),#spectacle article .large-up-7>.doc-examples:nth-of-type(7n+1),#spectacle article .prop-row .large-up-7>.prop-name:nth-of-type(7n+1),#spectacle article .prop-row .large-up-7>.prop-value:nth-of-type(7n+1){clear:both}#spectacle .large-up-7>.column:last-child,#spectacle .large-up-7>.columns:last-child,#spectacle article .large-up-7>.doc-copy:last-child,#spectacle article .large-up-7>.doc-examples:last-child,#spectacle article .prop-row .large-up-7>.prop-name:last-child,#spectacle article .prop-row .large-up-7>.prop-value:last-child{float:left}#spectacle .large-up-8>.column,#spectacle .large-up-8>.columns,#spectacle article .large-up-8>.doc-copy,#spectacle article .large-up-8>.doc-examples,#spectacle article .prop-row .large-up-8>.prop-name,#spectacle article .prop-row .large-up-8>.prop-value{float:left;width:12.5%}#spectacle .large-up-8>.column:nth-of-type(1n),#spectacle .large-up-8>.columns:nth-of-type(1n),#spectacle article .large-up-8>.doc-copy:nth-of-type(1n),#spectacle article .large-up-8>.doc-examples:nth-of-type(1n),#spectacle article .prop-row .large-up-8>.prop-name:nth-of-type(1n),#spectacle article .prop-row .large-up-8>.prop-value:nth-of-type(1n){clear:none}#spectacle .large-up-8>.column:nth-of-type(8n+1),#spectacle .large-up-8>.columns:nth-of-type(8n+1),#spectacle article .large-up-8>.doc-copy:nth-of-type(8n+1),#spectacle article .large-up-8>.doc-examples:nth-of-type(8n+1),#spectacle article .prop-row .large-up-8>.prop-name:nth-of-type(8n+1),#spectacle article .prop-row .large-up-8>.prop-value:nth-of-type(8n+1){clear:both}#spectacle .large-up-8>.column:last-child,#spectacle .large-up-8>.columns:last-child,#spectacle article .large-up-8>.doc-copy:last-child,#spectacle article .large-up-8>.doc-examples:last-child,#spectacle article .prop-row .large-up-8>.prop-name:last-child,#spectacle article .prop-row .large-up-8>.prop-value:last-child{float:left}#spectacle .large-collapse>.column,#spectacle .large-collapse>.columns,#spectacle article .large-collapse>.doc-copy,#spectacle article .large-collapse>.doc-examples,#spectacle article .prop-row .large-collapse>.prop-name,#spectacle article .prop-row .large-collapse>.prop-value{padding-right:0;padding-left:0}#spectacle .large-collapse .row,#spectacle .large-collapse article .doc-row,#spectacle .large-collapse article .prop-row,#spectacle article .large-collapse .doc-row,#spectacle article .large-collapse .prop-row{margin-right:0;margin-left:0}#spectacle .expanded.row .large-collapse.row,#spectacle .expanded.row article .large-collapse.doc-row,#spectacle .expanded.row article .large-collapse.prop-row,#spectacle article .expanded.doc-row .large-collapse.doc-row,#spectacle article .expanded.doc-row .large-collapse.prop-row,#spectacle article .expanded.doc-row .large-collapse.row,#spectacle article .expanded.prop-row .large-collapse.doc-row,#spectacle article .expanded.prop-row .large-collapse.prop-row,#spectacle article .expanded.prop-row .large-collapse.row,#spectacle article .expanded.row .large-collapse.doc-row,#spectacle article .expanded.row .large-collapse.prop-row{margin-right:0;margin-left:0}#spectacle .large-uncollapse>.column,#spectacle .large-uncollapse>.columns,#spectacle article .large-uncollapse>.doc-copy,#spectacle article .large-uncollapse>.doc-examples,#spectacle article .prop-row .large-uncollapse>.prop-name,#spectacle article .prop-row .large-uncollapse>.prop-value{padding-right:.9868421053rem;padding-left:.9868421053rem}#spectacle .large-centered{margin-right:auto;margin-left:auto}#spectacle .large-centered,#spectacle .large-centered:last-child:not(:first-child){float:none;clear:both}#spectacle .large-pull-0,#spectacle .large-push-0,#spectacle .large-uncentered{position:static;margin-right:0;margin-left:0}#spectacle .large-pull-0,#spectacle .large-pull-0:last-child:not(:first-child),#spectacle .large-push-0,#spectacle .large-push-0:last-child:not(:first-child),#spectacle .large-uncentered,#spectacle .large-uncentered:last-child:not(:first-child){float:left;clear:none}#spectacle .large-pull-0:last-child:not(:first-child),#spectacle .large-push-0:last-child:not(:first-child),#spectacle .large-uncentered:last-child:not(:first-child){float:right}}#spectacle .column-block{margin-bottom:1.3157894737rem}#spectacle .column-block>:last-child{margin-bottom:0}@media print,screen and (min-width:40em){#spectacle .column-block{margin-bottom:1.9736842105rem}#spectacle .column-block>:last-child{margin-bottom:0}}#spectacle #sidebar{padding-top:5rem;padding-left:1.5rem;padding-right:1rem;padding-bottom:3rem;border-right:1px solid #dae1e7;background-color:#f5f7f9;height:100vh;overflow:auto;position:fixed;bottom:0;left:0;top:0;width:250px}#spectacle #sidebar h5{margin:1.5rem 0 .65rem;color:#b6b6b6}#spectacle #sidebar a{display:block;margin:0 0 .25rem;color:#4a5055;white-space:nowrap;overflow:hidden;-o-text-overflow:ellipsis;text-overflow:ellipsis}#spectacle #sidebar a.active{color:#1779ba}#spectacle #sidebar ul{list-style-type:none;padding:0;margin:0 0 .75rem .75rem}#spectacle #sidebar section>ul{display:none}#spectacle #sidebar section.expand>ul{display:block}#spectacle #sidebar .close-button{opacity:.5}#spectacle .doc-content,#spectacle article .doc-copy,#spectacle article .doc-examples,#spectacle article .panel>h2,#spectacle article .panel>h3,#spectacle article h1.doc-title,#spectacle article h5.doc-intro-item,#spectacle article>h1,#spectacle article>h2{padding-left:1.5rem!important;padding-right:1.5rem!important}#spectacle .doc-separator,#spectacle article h2{margin-top:2em;padding-top:2em;padding-bottom:2em;border-top:1px solid #e2e2e2}#spectacle #docs{background:#fefefe;overflow:hidden;position:relative}#spectacle #docs .example-box{display:none}@media print,screen and (min-width:64em){#spectacle #docs .example-box{display:block;background-color:#202746;position:absolute;right:0;top:0;bottom:0}}#spectacle article{padding-top:64px;position:relative}#spectacle article .no-description{color:#8a8a8a}#spectacle article dt{color:#2d3134}#spectacle article table.table{width:100%}#spectacle article code{font-size:.9em;border-radius:3px}#spectacle article p:last-child:first-child{margin-bottom:0}#spectacle article h1{margin:2.5rem 0 0;padding-top:.75rem;padding-bottom:.75rem;padding-left:1.5rem;padding-right:1.5rem;border-top:1px solid #e8e8e8;border-bottom:1px solid #e2e2e2;background-color:#f6f6f6}#spectacle article h1.doc-title{margin:0;padding-top:2.15rem;padding-bottom:0;font-weight:700;background:0 0;border:none;color:#535b60}#spectacle article h2{margin-bottom:0;padding-left:1.5rem;padding-right:1.5rem;padding-bottom:.25rem;background-image:url(data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgi…gd2lkdGg9IjEwMCUiIGhlaWdodD0iMTAwJSIgZmlsbD0idXJsKCNncmFkKSIgLz48L3N2Zz4g);background-size:100%;background-image:-webkit-gradient(linear,50% 0,50% 100%,color-stop(0,rgba(255,255,255,.4)),color-stop(100%,rgba(255,255,255,0)));background-image:-moz-linear-gradient(top,rgba(255,255,255,.4),rgba(255,255,255,0));background-image:-webkit-linear-gradient(top,rgba(255,255,255,.4),rgba(255,255,255,0));background-image:linear-gradient(to bottom,rgba(255,255,255,.4),rgba(255,255,255,0))}#spectacle article h3{margin:0 0 .75rem}#spectacle article h1+.panel>h2{margin-top:0;border-top:none}#spectacle article h1+.tag-description+.panel>h2{margin-top:2rem}#spectacle article h1+.panel h3{margin-top:1rem}#spectacle article .panel{position:relative}#spectacle article .prop-row{padding-top:.75em;padding-bottom:.75em;border-top:1px solid #eee}#spectacle article .prop-row.prop-group,#spectacle article .prop-row:first-child{border-top:1px solid #ddd}#spectacle article .prop-row .prop-title{font-weight:700}#spectacle article .prop-row .prop-type{font-weight:400}#spectacle article .prop-row .prop-subtitle{font-weight:400;font-size:80%}#spectacle article .prop-row .prop-name{text-align:right;padding-right:.85rem!important;word-break:break-word}#spectacle article .prop-row .prop-value{padding-left:.85rem!important;word-wrap:break-word}#spectacle article .prop-row.prop-inner{padding-top:.5em;padding-bottom:.5em;font-size:80%}#spectacle article .prop-row.prop-inner .prop-name{color:#8a8a8a}#spectacle article .prop-row.prop-inner .prop-value>span{display:block}#spectacle article .prop-row.prop-inner .prop-value>span:before{color:#8a8a8a}#spectacle article .prop-row.prop-inner .prop-value>span:after{color:#8a8a8a}#spectacle article .prop-row.prop-inner .prop-value>span.json-property-format,#spectacle article .prop-row.prop-inner .prop-value>span.json-property-type{display:inline-block}#spectacle article .doc-row{margin:.5rem 0 20px}#spectacle article .doc-copy .operation-deprecation-reason{font-style:italic;opacity:75%}#spectacle article .doc-copy tr .enum-deprecation-reason,#spectacle article .doc-copy tr .properties-deprecation-reason{font-style:italic;opacity:75%}#spectacle article .doc-examples{padding-left:1.5rem!important;padding-right:1.5rem!important;color:#fefefe;background-color:#202746}#spectacle article .doc-examples h5{color:#fefefe;font-size:1rem;opacity:.8}#spectacle article .doc-examples h5 span{opacity:.5}@media print,screen and (max-width:63.99875em){#spectacle article .doc-examples:not(:empty){margin-top:1.5rem;padding-top:1.5rem;padding-bottom:.5rem}}#spectacle article .doc-examples code{display:block;margin-bottom:1.5rem;padding:1.5rem;font-family:Consolas,"Liberation Mono",Courier,monospace;font-weight:inherit;color:inherit;background-color:#202746;border:none;border-top:1px solid #000;border-bottom:1px solid #404040;border-radius:5px;box-shadow:0 0 200px rgba(0,0,0,.33) inset;word-spacing:normal;white-space:pre-wrap;word-break:normal}#spectacle article .doc-examples tbody tr:nth-child(even){border-bottom:0;background-color:#353a3d}#spectacle article .doc-examples tbody,#spectacle article .doc-examples tfoot,#spectacle article .doc-examples thead{color:#fff;background-color:#2d3134;border:0}#spectacle article .doc-examples thead{background-color:#2d3134}#spectacle article .doc-examples .swagger-response-headers{background-color:#202746;border:none;border-top:1px solid #000;border-bottom:1px solid #404040;border-radius:5px;box-shadow:0 0 200px rgba(0,0,0,.33) inset;margin-bottom:1.5rem}#spectacle article .doc-examples .swagger-response-headers thead{color:#fefefe;font-size:1rem;opacity:.8;background-color:transparent;border:none}#spectacle article .doc-examples .swagger-response-headers tbody{border:none;background-color:transparent}#spectacle article .doc-examples .swagger-response-headers tbody tr{background-color:transparent;border-top:1px solid #404040}#spectacle article .powered-by{font-size:80%;color:#cacaca}#spectacle article .powered-by span{color:#f68b1f}#spectacle article .operation .operation-tags{position:absolute;top:0;left:0}#spectacle article .operation .operation-tags .label{cursor:pointer}#spectacle article .operation .operation-tags .label:hover{color:#e6e6e6}@media print,screen and (min-width:64em){#spectacle article .operation .operation-tags{right:50%}}#spectacle article .operation .operation-path{word-break:break-all}#spectacle article .security-definition-description{margin-top:1.5rem;margin-bottom:.5rem}#spectacle article .security-definition-scope-description{color:#8a8a8a;margin-bottom:.5rem}#spectacle article .definition .definition-tags{position:absolute;top:0;left:0}#spectacle article .definition .definition-tags .label{cursor:pointer}#spectacle article .definition .definition-tags .label:hover{color:#e6e6e6}@media print,screen and (min-width:64em){#spectacle article .definition .definition-tags{right:50%}}#spectacle article .definition .doc-examples h5{margin-top:-1rem}#spectacle article .definition .doc-copy>section{margin-bottom:1rem}#spectacle article .definition .doc-copy>section>.json-property-type{display:none}#spectacle article .definition dl dt{font-weight:400}#spectacle article .definition dl dd{font-style:italic}#spectacle article .definition .json-property-name{font-weight:700}#spectacle article .hljs{line-height:1.25;overflow-x:auto;padding:1.5rem;margin-bottom:1rem;border:none}#spectacle .drawer-layout .drawer{transition:transform .5s ease;backface-visibility:hidden}#spectacle .drawer-layout .drawer.slide-left{transform:translateX(-250px)}#spectacle .drawer-layout .drawer.slide-right{transform:translateX(250px)}#spectacle .drawer-layout .drawer .drawer-overlay{position:absolute;top:0;left:0;right:0;bottom:0;background-color:rgba(254,254,254,.25)}@media print,screen and (min-width:64em){#spectacle .drawer-layout .drawer.slide-left{transform:none;margin-left:-250px}#spectacle .drawer-layout .drawer.slide-right{transform:none;margin-left:250px}#spectacle .drawer-layout .drawer .drawer-overlay{display:none}}@media print,screen and (min-width:64em){#spectacle .drawer-layout.drawer-slide-left-large .drawer{margin-left:-250px}#spectacle .drawer-layout.drawer-slide-left-large .floating-menu-icon{opacity:0}#spectacle .drawer-layout.drawer-slide-right-large .drawer{margin-left:250px}#spectacle .drawer-layout.drawer-slide-right-large .floating-menu-icon{opacity:0}}#spectacle .drawer-layout.drawer-open .floating-menu-icon{opacity:0}#spectacle .drawer-layout .floating-menu-icon{position:fixed;top:.75rem;left:.75rem;background-color:rgba(45,49,52,.75);padding:.65rem;z-index:1;border-radius:5px;transition:opacity .5s linear}#spectacle .drawer-layout .floating-menu-icon .hamburger{position:relative;display:inline-block;vertical-align:middle;width:20px;height:16px;cursor:pointer}#spectacle .drawer-layout .floating-menu-icon .hamburger::after{position:absolute;top:0;left:0;display:block;width:100%;height:2px;background:#fefefe;box-shadow:0 7px 0 #fefefe,0 14px 0 #fefefe;content:""}#spectacle .drawer-layout .floating-menu-icon .hamburger:hover::after{background:#cacaca;box-shadow:0 7px 0 #cacaca,0 14px 0 #cacaca}#spectacle .hljs{display:block;overflow-x:auto;padding:.5em;background:#23241f}#spectacle .hljs,#spectacle .hljs-subst,#spectacle .hljs-tag{color:#f8f8f2}#spectacle .hljs-emphasis,#spectacle .hljs-strong{color:#a8a8a2}#spectacle .hljs-bullet,#spectacle .hljs-link,#spectacle .hljs-literal,#spectacle .hljs-number,#spectacle .hljs-quote,#spectacle .hljs-regexp{color:#ae81ff}#spectacle .hljs-code,#spectacle .hljs-section,#spectacle .hljs-selector-class,#spectacle .hljs-title{color:#a6e22e}#spectacle .hljs-strong{font-weight:700}#spectacle .hljs-emphasis{font-style:italic}#spectacle .hljs-attr,#spectacle .hljs-keyword,#spectacle .hljs-name,#spectacle .hljs-selector-tag{color:#f92672}#spectacle .hljs-attribute,#spectacle .hljs-symbol{color:#66d9ef}#spectacle .hljs-class .hljs-title,#spectacle .hljs-params{color:#f8f8f2}#spectacle .hljs-addition,#spectacle .hljs-built_in,#spectacle .hljs-builtin-name,#spectacle .hljs-selector-attr,#spectacle .hljs-selector-id,#spectacle .hljs-selector-pseudo,#spectacle .hljs-string,#spectacle .hljs-template-variable,#spectacle .hljs-type,#spectacle .hljs-variable{color:#e6db74}#spectacle .hljs-comment,#spectacle .hljs-deletion,#spectacle .hljs-meta{color:#75715e}</style> -<link rel="preconnect" href="https://fonts.gstatic.com"> -<link href="https://fonts.googleapis.com/css2?family=Source+Sans+Pro:wght@400;600;700&display=swap" rel="stylesheet"> -<div id="spectacle"> - <div id="page" class="drawer-layout drawer-slide-right-large"> - <div id="sidebar"> - <button id="close-button" class="close-button" aria-label="Close menu" type="button" data-drawer-close> - <span aria-hidden="true">×</span> - </button> - <nav id="nav" role="navigation"> - <h5>Operations</h5> - <section> - <a href="#tag-Queries">Queries</a> - <ul> - <li> - <a href="#operation-customer-post"> customer </a> - </li> - <li> - <a href="#operation-inventory-post"> inventory </a> - </li> - <li> - <a href="#operation-site-post"> site </a> - </li> - </ul> - </section> - <section> - <a href="#tag-Mutations">Mutations</a> - <ul> - <li> - <a href="#operation-login-post"> login </a> - </li> - <li> - <a href="#operation-logout-post"> logout </a> - </li> - </ul> - </section> - <h5>Types</h5> - <a href="#definition-Aggregated"> Aggregated </a> - <a href="#definition-AggregatedInventory"> AggregatedInventory </a> - <a href="#definition-Author"> Author </a> - <a href="#definition-BigDecimal"> BigDecimal </a> - <a href="#definition-Boolean"> Boolean </a> - <a href="#definition-Brand"> Brand </a> - <a href="#definition-BrandConnection"> BrandConnection </a> - <a href="#definition-BrandEdge"> BrandEdge </a> - <a href="#definition-Breadcrumb"> Breadcrumb </a> - <a href="#definition-BreadcrumbConnection"> BreadcrumbConnection </a> - <a href="#definition-BreadcrumbEdge"> BreadcrumbEdge </a> - <a href="#definition-BulkPricingFixedPriceDiscount"> BulkPricingFixedPriceDiscount </a> - <a href="#definition-BulkPricingPercentageDiscount"> BulkPricingPercentageDiscount </a> - <a href="#definition-BulkPricingRelativePriceDiscount"> BulkPricingRelativePriceDiscount </a> - <a href="#definition-Category"> Category </a> - <a href="#definition-CategoryConnection"> CategoryConnection </a> - <a href="#definition-CategoryEdge"> CategoryEdge </a> - <a href="#definition-CategoryProductSort"> CategoryProductSort </a> - <a href="#definition-CategoryTreeItem"> CategoryTreeItem </a> - <a href="#definition-CheckboxOption"> CheckboxOption </a> - <a href="#definition-ContactField"> ContactField </a> - <a href="#definition-Content"> Content </a> - <a href="#definition-Currency"> Currency </a> - <a href="#definition-CurrencyConnection"> CurrencyConnection </a> - <a href="#definition-CurrencyDisplay"> CurrencyDisplay </a> - <a href="#definition-CurrencyEdge"> CurrencyEdge </a> - <a href="#definition-CurrencySymbolPosition"> CurrencySymbolPosition </a> - <a href="#definition-CustomField"> CustomField </a> - <a href="#definition-CustomFieldConnection"> CustomFieldConnection </a> - <a href="#definition-CustomFieldEdge"> CustomFieldEdge </a> - <a href="#definition-Customer"> Customer </a> - <a href="#definition-CustomerAttribute"> CustomerAttribute </a> - <a href="#definition-CustomerAttributes"> CustomerAttributes </a> - <a href="#definition-DateFieldOption"> DateFieldOption </a> - <a href="#definition-DateTime"> DateTime </a> - <a href="#definition-DateTimeExtended"> DateTimeExtended </a> - <a href="#definition-DisplayField"> DisplayField </a> - <a href="#definition-Distance"> Distance </a> - <a href="#definition-DistanceFilter"> DistanceFilter </a> - <a href="#definition-EntityPageType"> EntityPageType </a> - <a href="#definition-FileUploadFieldOption"> FileUploadFieldOption </a> - <a href="#definition-Float"> Float </a> - <a href="#definition-ID"> ID </a> - <a href="#definition-Image"> Image </a> - <a href="#definition-ImageConnection"> ImageConnection </a> - <a href="#definition-ImageEdge"> ImageEdge </a> - <a href="#definition-Int"> Int </a> - <a href="#definition-Inventory"> Inventory </a> - <a href="#definition-InventoryByLocations"> InventoryByLocations </a> - <a href="#definition-LengthUnit"> LengthUnit </a> - <a href="#definition-LocationConnection"> LocationConnection </a> - <a href="#definition-LocationEdge"> LocationEdge </a> - <a href="#definition-LoginResult"> LoginResult </a> - <a href="#definition-LogoField"> LogoField </a> - <a href="#definition-LogoutResult"> LogoutResult </a> - <a href="#definition-Long"> Long </a> - <a href="#definition-Measurement"> Measurement </a> - <a href="#definition-MetafieldConnection"> MetafieldConnection </a> - <a href="#definition-MetafieldEdge"> MetafieldEdge </a> - <a href="#definition-Metafields"> Metafields </a> - <a href="#definition-Money"> Money </a> - <a href="#definition-MoneyRange"> MoneyRange </a> - <a href="#definition-MultiLineTextFieldOption"> MultiLineTextFieldOption </a> - <a href="#definition-MultipleChoiceOption"> MultipleChoiceOption </a> - <a href="#definition-MultipleChoiceOptionValue"> MultipleChoiceOptionValue </a> - <a href="#definition-NumberFieldOption"> NumberFieldOption </a> - <a href="#definition-OptionConnection"> OptionConnection </a> - <a href="#definition-OptionEdge"> OptionEdge </a> - <a href="#definition-OptionValueConnection"> OptionValueConnection </a> - <a href="#definition-OptionValueEdge"> OptionValueEdge </a> - <a href="#definition-OptionValueId"> OptionValueId </a> - <a href="#definition-PageInfo"> PageInfo </a> - <a href="#definition-PageType"> PageType </a> - <a href="#definition-PriceRanges"> PriceRanges </a> - <a href="#definition-PriceSearchFilterInput"> PriceSearchFilterInput </a> - <a href="#definition-Prices"> Prices </a> - <a href="#definition-Product"> Product </a> - <a href="#definition-ProductAttributeSearchFilterInput"> ProductAttributeSearchFilterInput </a> - <a href="#definition-ProductAvailabilityStatus"> ProductAvailabilityStatus </a> - <a href="#definition-ProductAvailable"> ProductAvailable </a> - <a href="#definition-ProductConnection"> ProductConnection </a> - <a href="#definition-ProductEdge"> ProductEdge </a> - <a href="#definition-ProductInventory"> ProductInventory </a> - <a href="#definition-ProductOption"> ProductOption </a> - <a href="#definition-ProductOptionConnection"> ProductOptionConnection </a> - <a href="#definition-ProductOptionEdge"> ProductOptionEdge </a> - <a href="#definition-ProductOptionValue"> ProductOptionValue </a> - <a href="#definition-ProductOptionValueConnection"> ProductOptionValueConnection </a> - <a href="#definition-ProductOptionValueEdge"> ProductOptionValueEdge </a> - <a href="#definition-ProductPickListOptionValue"> ProductPickListOptionValue </a> - <a href="#definition-ProductPreOrder"> ProductPreOrder </a> - <a href="#definition-ProductReviewsSortInput"> ProductReviewsSortInput </a> - <a href="#definition-ProductUnavailable"> ProductUnavailable </a> - <a href="#definition-RatingSearchFilterInput"> RatingSearchFilterInput </a> - <a href="#definition-Region"> Region </a> - <a href="#definition-RelatedProductsConnection"> RelatedProductsConnection </a> - <a href="#definition-RelatedProductsEdge"> RelatedProductsEdge </a> - <a href="#definition-RenderedRegionsByPageType"> RenderedRegionsByPageType </a> - <a href="#definition-Review"> Review </a> - <a href="#definition-ReviewConnection"> ReviewConnection </a> - <a href="#definition-ReviewEdge"> ReviewEdge </a> - <a href="#definition-Reviews"> Reviews </a> - <a href="#definition-Route"> Route </a> - <a href="#definition-Search"> Search </a> - <a href="#definition-SearchProducts"> SearchProducts </a> - <a href="#definition-SearchProductsFiltersInput"> SearchProductsFiltersInput </a> - <a href="#definition-SearchProductsSortInput"> SearchProductsSortInput </a> - <a href="#definition-SearchQueries"> SearchQueries </a> - <a href="#definition-SeoDetails"> SeoDetails </a> - <a href="#definition-Settings"> Settings </a> - <a href="#definition-Site"> Site </a> - <a href="#definition-StorefrontStatusType"> StorefrontStatusType </a> - <a href="#definition-String"> String </a> - <a href="#definition-SwatchOptionValue"> SwatchOptionValue </a> - <a href="#definition-TaxDisplaySettings"> TaxDisplaySettings </a> - <a href="#definition-TaxPriceDisplay"> TaxPriceDisplay </a> - <a href="#definition-TextFieldOption"> TextFieldOption </a> - <a href="#definition-UrlField"> UrlField </a> - <a href="#definition-Variant"> Variant </a> - <a href="#definition-VariantConnection"> VariantConnection </a> - <a href="#definition-VariantEdge"> VariantEdge </a> - <a href="#definition-VariantInventory"> VariantInventory </a> - <a href="#definition-countryCode"> countryCode </a> - <a href="#definition-currencyCode"> currencyCode </a> - </nav> - </div> - <div id="docs" class="row collapse expanded drawer" data-drawer> - <button class="floating-menu-icon" type="button" data-drawer-slide="right"> - <span class="hamburger"></span> - </button> - <div class="example-box doc-content"></div> - <article id="content"> - <h1 class="doc-title">Storefront GraphQL API Reference</h1> - <h1 id="tag-Queries" class="swagger-summary-tag tag-name" data-traverse-target="tag-Queries">Queries</h1> - <div id="operation-customer-post" class="operation panel" data-traverse-target="operation-customer-post"> - <h2 class="operation-name "> <code>customer</code> </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="swagger-operation-description operation-description"> The currently logged in customer </section> - </div> - </div> - <div class="doc-row"> - <div class="doc-copy"> - <section class="swagger-request-body"> </section> - <section class="swagger-responses"> Returns a - <a href="#definition-Customer"><code>Customer</code></a> - </section> - <br> </div> - <div class="doc-examples"> - <section> - <h4>Example</h3> - <h5>Query</h5> - <html> - <head></head> - <body><pre><code class="hljs language-gql"><span class="hljs-symbol"><span class="hljs-keyword">query</span> customer <span class="hljs-tag">{ - <span class="hljs-symbol">customer <span class="hljs-tag">{ - <span class="hljs-symbol">entityId</span> - <span class="hljs-symbol">company</span> - <span class="hljs-symbol">customerGroupId</span> - <span class="hljs-symbol">email</span> - <span class="hljs-symbol">firstName</span> - <span class="hljs-symbol">lastName</span> - <span class="hljs-symbol">notes</span> - <span class="hljs-symbol">phone</span> - <span class="hljs-symbol">taxExemptCategory</span> - <span class="hljs-symbol">addressCount</span> - <span class="hljs-symbol">attributeCount</span> - <span class="hljs-symbol">storeCredit <span class="hljs-tag">{ - <span class="hljs-type">...MoneyFragment</span> - }</span></span> - <span class="hljs-symbol">attributes <span class="hljs-tag">{ - <span class="hljs-type">...CustomerAttributesFragment</span> - }</span></span> - }</span></span> -}</span></span> -</code></pre> </body> - </html> - </section> - </div> - </div> - <div class="doc-row"> - <div class="doc-copy"> </div> - <div class="doc-examples"> - <section> - <h5>Response </h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"data"</span>: { - <span class="hljs-attr">"customer"</span>: { - <span class="hljs-attr">"entityId"</span>: <span class="hljs-number">123</span>, - <span class="hljs-attr">"company"</span>: <span class="hljs-string">"xyz789"</span>, - <span class="hljs-attr">"customerGroupId"</span>: <span class="hljs-number">987</span>, - <span class="hljs-attr">"email"</span>: <span class="hljs-string">"xyz789"</span>, - <span class="hljs-attr">"firstName"</span>: <span class="hljs-string">"xyz789"</span>, - <span class="hljs-attr">"lastName"</span>: <span class="hljs-string">"xyz789"</span>, - <span class="hljs-attr">"notes"</span>: <span class="hljs-string">"abc123"</span>, - <span class="hljs-attr">"phone"</span>: <span class="hljs-string">"xyz789"</span>, - <span class="hljs-attr">"taxExemptCategory"</span>: <span class="hljs-string">"abc123"</span>, - <span class="hljs-attr">"addressCount"</span>: <span class="hljs-number">123</span>, - <span class="hljs-attr">"attributeCount"</span>: <span class="hljs-number">987</span>, - <span class="hljs-attr">"storeCredit"</span>: [Money], - <span class="hljs-attr">"attributes"</span>: CustomerAttributes - } - } -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="operation-inventory-post" class="operation panel" data-traverse-target="operation-inventory-post"> - <!-- <section class="operation-tags row"> --> - <!-- <div class="doc-copy"> --> - <div class="operation-tags"> - <a class="label" href="#tag-Queries">Queries</a> - <!----> - </div> - <!-- </div> --> - <!-- </section> --> - <h2 class="operation-name swagger-operation-deprecated"> <code>inventory</code> </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="operation-deprecation-reason"> Alpha version. Do not use in production. </section> - </div> - </div> - <div class="doc-row"> - <div class="doc-copy"> - <section class="swagger-request-body"> </section> - <section class="swagger-responses"> Returns an - <a href="#definition-Inventory"><code>Inventory!</code></a> - </section> - <br> </div> - <div class="doc-examples"> - <section> - <h4>Example</h3> - <h5>Query</h5> - <html> - <head></head> - <body><pre><code class="hljs language-gql"><span class="hljs-symbol"><span class="hljs-keyword">query</span> inventory <span class="hljs-tag">{ - <span class="hljs-symbol">inventory <span class="hljs-tag">{ - <span class="hljs-symbol">locations<span class="hljs-tag">(entityIds: <span class="hljs-code">$entityIds</span>, codes: <span class="hljs-code">$codes</span>, typeIds: <span class="hljs-code">$typeIds</span>, serviceTypeIds: <span class="hljs-code">$serviceTypeIds</span>, distanceFilter: <span class="hljs-code">$distanceFilter</span>, countryCodes: <span class="hljs-code">$countryCodes</span>, states: <span class="hljs-code">$states</span>, cities: <span class="hljs-code">$cities</span>, before: <span class="hljs-code">$before</span>, after: <span class="hljs-code">$after</span>, first: <span class="hljs-code">$first</span>, last: <span class="hljs-code">$last</span>)</span> <span class="hljs-tag">{ - <span class="hljs-type">...LocationConnectionFragment</span> - }</span></span> - }</span></span> -}</span></span> -</code></pre> </body> - </html> - </section> - </div> - </div> - <div class="doc-row"> - <div class="doc-copy"> </div> - <div class="doc-examples"> - <section> - <h5>Response </h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"data"</span>: {<span class="hljs-attr">"inventory"</span>: {<span class="hljs-attr">"locations"</span>: LocationConnection}}} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="operation-site-post" class="operation panel" data-traverse-target="operation-site-post"> - <!-- <section class="operation-tags row"> --> - <!-- <div class="doc-copy"> --> - <div class="operation-tags"> - <a class="label" href="#tag-Queries">Queries</a> - <!----> - </div> - <!-- </div> --> - <!-- </section> --> - <h2 class="operation-name "> <code>site</code> </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="swagger-request-body"> </section> - <section class="swagger-responses"> Returns a - <a href="#definition-Site"><code>Site!</code></a> - </section> - <br> </div> - <div class="doc-examples"> - <section> - <h4>Example</h3> - <h5>Query</h5> - <html> - <head></head> - <body><pre><code class="hljs language-gql"><span class="hljs-symbol"><span class="hljs-keyword">query</span> site <span class="hljs-tag">{ - <span class="hljs-symbol">site <span class="hljs-tag">{ - <span class="hljs-symbol">search <span class="hljs-tag">{ - <span class="hljs-type">...SearchQueriesFragment</span> - }</span></span> - <span class="hljs-symbol">categoryTree<span class="hljs-tag">(rootEntityId: <span class="hljs-code">$rootEntityId</span>)</span> <span class="hljs-tag">{ - <span class="hljs-type">...CategoryTreeItemFragment</span> - }</span></span> - <span class="hljs-symbol">brands<span class="hljs-tag">(before: <span class="hljs-code">$before</span>, after: <span class="hljs-code">$after</span>, first: <span class="hljs-code">$first</span>, last: <span class="hljs-code">$last</span>, productEntityIds: <span class="hljs-code">$productEntityIds</span>)</span> <span class="hljs-tag">{ - <span class="hljs-type">...BrandConnectionFragment</span> - }</span></span> - <span class="hljs-symbol">products<span class="hljs-tag">(before: <span class="hljs-code">$before</span>, after: <span class="hljs-code">$after</span>, first: <span class="hljs-code">$first</span>, last: <span class="hljs-code">$last</span>, ids: <span class="hljs-code">$ids</span>, entityIds: <span class="hljs-code">$entityIds</span>, hideOutOfStock: <span class="hljs-code">$hideOutOfStock</span>)</span> <span class="hljs-tag">{ - <span class="hljs-type">...ProductConnectionFragment</span> - }</span></span> - <span class="hljs-symbol">newestProducts<span class="hljs-tag">(before: <span class="hljs-code">$before</span>, after: <span class="hljs-code">$after</span>, first: <span class="hljs-code">$first</span>, last: <span class="hljs-code">$last</span>, hideOutOfStock: <span class="hljs-code">$hideOutOfStock</span>)</span> <span class="hljs-tag">{ - <span class="hljs-type">...ProductConnectionFragment</span> - }</span></span> - <span class="hljs-symbol">bestSellingProducts<span class="hljs-tag">(before: <span class="hljs-code">$before</span>, after: <span class="hljs-code">$after</span>, first: <span class="hljs-code">$first</span>, last: <span class="hljs-code">$last</span>, hideOutOfStock: <span class="hljs-code">$hideOutOfStock</span>)</span> <span class="hljs-tag">{ - <span class="hljs-type">...ProductConnectionFragment</span> - }</span></span> - <span class="hljs-symbol">featuredProducts<span class="hljs-tag">(before: <span class="hljs-code">$before</span>, after: <span class="hljs-code">$after</span>, first: <span class="hljs-code">$first</span>, last: <span class="hljs-code">$last</span>, hideOutOfStock: <span class="hljs-code">$hideOutOfStock</span>)</span> <span class="hljs-tag">{ - <span class="hljs-type">...ProductConnectionFragment</span> - }</span></span> - <span class="hljs-symbol">product<span class="hljs-tag">(id: <span class="hljs-code">$id</span>, entityId: <span class="hljs-code">$entityId</span>, variantEntityId: <span class="hljs-code">$variantEntityId</span>, optionValueIds: <span class="hljs-code">$optionValueIds</span>, sku: <span class="hljs-code">$sku</span>)</span> <span class="hljs-tag">{ - <span class="hljs-type">...ProductFragment</span> - }</span></span> - <span class="hljs-symbol">route<span class="hljs-tag">(path: <span class="hljs-code">$path</span>)</span> <span class="hljs-tag">{ - <span class="hljs-type">...RouteFragment</span> - }</span></span> - <span class="hljs-symbol">settings <span class="hljs-tag">{ - <span class="hljs-type">...SettingsFragment</span> - }</span></span> - <span class="hljs-symbol">content <span class="hljs-tag">{ - <span class="hljs-type">...ContentFragment</span> - }</span></span> - <span class="hljs-symbol">currency<span class="hljs-tag">(currencyCode: <span class="hljs-code">$currencyCode</span>)</span> <span class="hljs-tag">{ - <span class="hljs-type">...CurrencyFragment</span> - }</span></span> - <span class="hljs-symbol">currencies<span class="hljs-tag">(before: <span class="hljs-code">$before</span>, after: <span class="hljs-code">$after</span>, first: <span class="hljs-code">$first</span>, last: <span class="hljs-code">$last</span>)</span> <span class="hljs-tag">{ - <span class="hljs-type">...CurrencyConnectionFragment</span> - }</span></span> - }</span></span> -}</span></span> -</code></pre> </body> - </html> - </section> - </div> - </div> - <div class="doc-row"> - <div class="doc-copy"> </div> - <div class="doc-examples"> - <section> - <h5>Response </h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"data"</span>: { - <span class="hljs-attr">"site"</span>: { - <span class="hljs-attr">"search"</span>: SearchQueries, - <span class="hljs-attr">"categoryTree"</span>: [CategoryTreeItem], - <span class="hljs-attr">"brands"</span>: BrandConnection, - <span class="hljs-attr">"products"</span>: ProductConnection, - <span class="hljs-attr">"newestProducts"</span>: ProductConnection, - <span class="hljs-attr">"bestSellingProducts"</span>: ProductConnection, - <span class="hljs-attr">"featuredProducts"</span>: ProductConnection, - <span class="hljs-attr">"product"</span>: Product, - <span class="hljs-attr">"route"</span>: Route, - <span class="hljs-attr">"settings"</span>: Settings, - <span class="hljs-attr">"content"</span>: Content, - <span class="hljs-attr">"currency"</span>: Currency, - <span class="hljs-attr">"currencies"</span>: CurrencyConnection - } - } -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <h1 id="tag-Mutations" class="swagger-summary-tag tag-name" data-traverse-target="tag-Mutations">Mutations</h1> - <div id="operation-login-post" class="operation panel" data-traverse-target="operation-login-post"> - <h2 class="operation-name "> <code>login</code> </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="swagger-request-body"> </section> - <section class="swagger-responses"> Returns a - <a href="#definition-LoginResult"><code>LoginResult!</code></a> - </section> - <br> - <section class="swagger-request-params"> - <table> - <tr> - <th>Name</th> - <th>Description</th> - </tr> - <tr> - <td><code>email</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> </td> - </tr> - <tr> - <td><code>password</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h4>Example</h3> - <h5>Query</h5> - <html> - <head></head> - <body><pre><code class="hljs language-gql"><span class="hljs-symbol"><span class="hljs-keyword">mutation</span> login<span class="hljs-tag">(<span class="hljs-code">$email</span>:<span class="hljs-type"> String!</span>, <span class="hljs-code">$password</span>:<span class="hljs-type"> String!</span>)</span> <span class="hljs-tag">{ - <span class="hljs-symbol">login<span class="hljs-tag">(email: <span class="hljs-code">$email</span>, password: <span class="hljs-code">$password</span>)</span> <span class="hljs-tag">{ - <span class="hljs-symbol">result</span> - <span class="hljs-symbol">customer <span class="hljs-tag">{ - <span class="hljs-type">...CustomerFragment</span> - }</span></span> - }</span></span> -}</span></span> -</code></pre> </body> - </html> - <h5>Variables</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"email"</span>: <span class="hljs-string">"abc123"</span>, <span class="hljs-attr">"password"</span>: <span class="hljs-string">"abc123"</span>} -</code></pre> </body> - </html> - </section> - </div> - </div> - <div class="doc-row"> - <div class="doc-copy"> </div> - <div class="doc-examples"> - <section> - <h5>Response </h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"data"</span>: { - <span class="hljs-attr">"login"</span>: {<span class="hljs-attr">"result"</span>: <span class="hljs-string">"abc123"</span>, <span class="hljs-attr">"customer"</span>: Customer} - } -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="operation-logout-post" class="operation panel" data-traverse-target="operation-logout-post"> - <!-- <section class="operation-tags row"> --> - <!-- <div class="doc-copy"> --> - <div class="operation-tags"> - <a class="label" href="#tag-Mutations">Mutations</a> - <!----> - </div> - <!-- </div> --> - <!-- </section> --> - <h2 class="operation-name "> <code>logout</code> </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="swagger-request-body"> </section> - <section class="swagger-responses"> Returns a - <a href="#definition-LogoutResult"><code>LogoutResult!</code></a> - </section> - <br> </div> - <div class="doc-examples"> - <section> - <h4>Example</h3> - <h5>Query</h5> - <html> - <head></head> - <body><pre><code class="hljs language-gql"><span class="hljs-symbol"><span class="hljs-keyword">mutation</span> logout <span class="hljs-tag">{ - <span class="hljs-symbol">logout <span class="hljs-tag">{ - <span class="hljs-symbol">result</span> - }</span></span> -}</span></span> -</code></pre> </body> - </html> - </section> - </div> - </div> - <div class="doc-row"> - <div class="doc-copy"> </div> - <div class="doc-examples"> - <section> - <h5>Response </h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"data"</span>: {<span class="hljs-attr">"logout"</span>: {<span class="hljs-attr">"result"</span>: <span class="hljs-string">"xyz789"</span>}}} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <span id="tag-types"></span> - <h1>Types</h1> - <div id="definition-Aggregated" class="definition panel" data-traverse-target="definition-Aggregated"> - <h2 class="panel-title"> - <a name="/definitions/Aggregated"></a> - <p><code>Aggregated</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Aggregated</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="availableToSell"> <code>availableToSell</code> - - <a href="#definition-Long"><code>Long!</code></a> - </td> - <td> Number of available products in stock. This can be 'null' if inventory is not set orif the store's Inventory Settings disable displaying stock levels on the storefront. </td> - </tr> - <tr> - <td data-property-name="warningLevel"> <code>warningLevel</code> - - <a href="#definition-Int"><code>Int!</code></a> - </td> - <td> Indicates a threshold low-stock level. This can be 'null' if the inventory warning level is not set or if the store's Inventory Settings disable displaying stock levels on the storefront. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"availableToSell"</span>: Long, <span class="hljs-attr">"warningLevel"</span>: <span class="hljs-number">123</span>} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-AggregatedInventory" class="definition panel" data-traverse-target="definition-AggregatedInventory"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/AggregatedInventory"></a> - <p><code>AggregatedInventory</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Aggregated Product Inventory</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="availableToSell"> <code>availableToSell</code> - - <a href="#definition-Int"><code>Int!</code></a> - </td> - <td> Number of available products in stock. This can be 'null' if inventory is not set orif the store's Inventory Settings disable displaying stock levels on the storefront. </td> - </tr> - <tr> - <td data-property-name="warningLevel"> <code>warningLevel</code> - - <a href="#definition-Int"><code>Int!</code></a> - </td> - <td> Indicates a threshold low-stock level. This can be 'null' if the inventory warning level is not set or if the store's Inventory Settings disable displaying stock levels on the storefront. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"availableToSell"</span>: <span class="hljs-number">123</span>, <span class="hljs-attr">"warningLevel"</span>: <span class="hljs-number">987</span>} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-Author" class="definition panel" data-traverse-target="definition-Author"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/Author"></a> - <p><code>Author</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Author</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="name"> <code>name</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Author name. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"name"</span>: <span class="hljs-string">"abc123"</span>} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-BigDecimal" class="definition panel" data-traverse-target="definition-BigDecimal"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/BigDecimal"></a> - <p><code>BigDecimal</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>The <code>BigDecimal</code> scalar type represents signed fractional values with arbitrary precision.</p> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-gql"><span class="hljs-symbol">object</span> -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-Boolean" class="definition panel" data-traverse-target="definition-Boolean"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/Boolean"></a> - <p><code>Boolean</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>The <code>Boolean</code> scalar type represents <code>true</code> or <code>false</code>.</p> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-gql"><span class="hljs-symbol"><span class="hljs-literal">true</span></span> -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-Brand" class="definition panel" data-traverse-target="definition-Brand"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/Brand"></a> - <p><code>Brand</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Brand</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="id"> <code>id</code> - - <a href="#definition-ID"><code>ID!</code></a> - </td> - <td> The ID of an object </td> - </tr> - <tr> - <td data-property-name="entityId"> <code>entityId</code> - - <a href="#definition-Int"><code>Int!</code></a> - </td> - <td> Id of the brand. </td> - </tr> - <tr> - <td data-property-name="name"> <code>name</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Name of the brand. </td> - </tr> - <tr> - <td data-property-name="defaultImage"> <code>defaultImage</code> - - <a href="#definition-Image"><code>Image</code></a> - </td> - <td> Default image for brand. </td> - </tr> - <tr> - <td data-property-name="pageTitle" class="swagger-operation-deprecated"> <code>pageTitle</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Page title for the brand. - <span class="properties-deprecation-reason">Use SEO details instead.</span> - </td> - </tr> - <tr> - <td data-property-name="metaDesc" class="swagger-operation-deprecated"> <code>metaDesc</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Meta description for the brand. - <span class="properties-deprecation-reason">Use SEO details instead.</span> - </td> - </tr> - <tr> - <td data-property-name="metaKeywords" class="swagger-operation-deprecated"> <code>metaKeywords</code> - - <a href="#definition-String"><code>[String!]!</code></a> - </td> - <td> Meta keywords for the brand. - <span class="properties-deprecation-reason">Use SEO details instead.</span> - </td> - </tr> - <tr> - <td data-property-name="seo"> <code>seo</code> - - <a href="#definition-SeoDetails"><code>SeoDetails!</code></a> - </td> - <td> Brand SEO details. </td> - </tr> - <tr> - <td data-property-name="searchKeywords"> <code>searchKeywords</code> - - <a href="#definition-String"><code>[String!]!</code></a> - </td> - <td> Search keywords for the brand. </td> - </tr> - <tr> - <td data-property-name="path"> <code>path</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Path for the brand page. </td> - </tr> - <tr> - <td data-property-name="products"> <code>products</code> - - <a href="#definition-ProductConnection"><code>ProductConnection!</code></a> - </td> - <td> </td> - </tr> - <tr> - <td colspan="2" class="no-top-border"> - <div class="field-arguments"> - <p class="field-arguments-header"> Arguments </p> - <div class="field-argument"> - <p class="field-argument-name"><code>before</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>after</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>first</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>last</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>hideOutOfStock</code> - - <a href="#definition-Boolean"><code>Boolean</code></a> - </p> - </div> - </div> - </td> - </tr> - <tr> - <td data-property-name="metafields"> <code>metafields</code> - - <a href="#definition-MetafieldConnection"><code>MetafieldConnection!</code></a> - </td> - <td> Metafield data related to a brand. </td> - </tr> - <tr> - <td colspan="2" class="no-top-border"> - <div class="field-arguments"> - <p class="field-arguments-header"> Arguments </p> - <div class="field-argument"> - <p class="field-argument-name"><code>namespace</code> - - <a href="#definition-String"><code>String!</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>keys</code> - - <a href="#definition-String"><code>[String!]</code></a> default = <code>[]</code></p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>before</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>after</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>first</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>last</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - </div> - </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"id"</span>: ID, - <span class="hljs-attr">"entityId"</span>: <span class="hljs-number">123</span>, - <span class="hljs-attr">"name"</span>: <span class="hljs-string">"xyz789"</span>, - <span class="hljs-attr">"defaultImage"</span>: Image, - <span class="hljs-attr">"pageTitle"</span>: <span class="hljs-string">"xyz789"</span>, - <span class="hljs-attr">"metaDesc"</span>: <span class="hljs-string">"xyz789"</span>, - <span class="hljs-attr">"metaKeywords"</span>: [<span class="hljs-string">"abc123"</span>], - <span class="hljs-attr">"seo"</span>: SeoDetails, - <span class="hljs-attr">"searchKeywords"</span>: [<span class="hljs-string">"abc123"</span>], - <span class="hljs-attr">"path"</span>: <span class="hljs-string">"abc123"</span>, - <span class="hljs-attr">"products"</span>: ProductConnection, - <span class="hljs-attr">"metafields"</span>: MetafieldConnection -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-BrandConnection" class="definition panel" data-traverse-target="definition-BrandConnection"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/BrandConnection"></a> - <p><code>BrandConnection</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>A connection to a list of items.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="pageInfo"> <code>pageInfo</code> - - <a href="#definition-PageInfo"><code>PageInfo!</code></a> - </td> - <td> Information to aid in pagination. </td> - </tr> - <tr> - <td data-property-name="edges"> <code>edges</code> - - <a href="#definition-BrandEdge"><code>[BrandEdge]</code></a> - </td> - <td> A list of edges. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"pageInfo"</span>: PageInfo, - <span class="hljs-attr">"edges"</span>: [BrandEdge] -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-BrandEdge" class="definition panel" data-traverse-target="definition-BrandEdge"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/BrandEdge"></a> - <p><code>BrandEdge</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>An edge in a connection.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="node"> <code>node</code> - - <a href="#definition-Brand"><code>Brand!</code></a> - </td> - <td> The item at the end of the edge. </td> - </tr> - <tr> - <td data-property-name="cursor"> <code>cursor</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> A cursor for use in pagination. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"node"</span>: Brand, <span class="hljs-attr">"cursor"</span>: <span class="hljs-string">"abc123"</span>} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-Breadcrumb" class="definition panel" data-traverse-target="definition-Breadcrumb"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/Breadcrumb"></a> - <p><code>Breadcrumb</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Breadcrumb</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="entityId"> <code>entityId</code> - - <a href="#definition-Int"><code>Int!</code></a> - </td> - <td> Category id. </td> - </tr> - <tr> - <td data-property-name="name"> <code>name</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Name of the category. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"entityId"</span>: <span class="hljs-number">123</span>, <span class="hljs-attr">"name"</span>: <span class="hljs-string">"abc123"</span>} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-BreadcrumbConnection" class="definition panel" data-traverse-target="definition-BreadcrumbConnection"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/BreadcrumbConnection"></a> - <p><code>BreadcrumbConnection</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>A connection to a list of items.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="pageInfo"> <code>pageInfo</code> - - <a href="#definition-PageInfo"><code>PageInfo!</code></a> - </td> - <td> Information to aid in pagination. </td> - </tr> - <tr> - <td data-property-name="edges"> <code>edges</code> - - <a href="#definition-BreadcrumbEdge"><code>[BreadcrumbEdge]</code></a> - </td> - <td> A list of edges. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"pageInfo"</span>: PageInfo, - <span class="hljs-attr">"edges"</span>: [BreadcrumbEdge] -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-BreadcrumbEdge" class="definition panel" data-traverse-target="definition-BreadcrumbEdge"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/BreadcrumbEdge"></a> - <p><code>BreadcrumbEdge</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>An edge in a connection.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="node"> <code>node</code> - - <a href="#definition-Breadcrumb"><code>Breadcrumb!</code></a> - </td> - <td> The item at the end of the edge. </td> - </tr> - <tr> - <td data-property-name="cursor"> <code>cursor</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> A cursor for use in pagination. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"node"</span>: Breadcrumb, <span class="hljs-attr">"cursor"</span>: <span class="hljs-string">"abc123"</span>} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-BulkPricingFixedPriceDiscount" class="definition panel" data-traverse-target="definition-BulkPricingFixedPriceDiscount"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/BulkPricingFixedPriceDiscount"></a> - <p><code>BulkPricingFixedPriceDiscount</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Bulk pricing tier that sets a fixed price for the product or variant.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="price"> <code>price</code> - - <a href="#definition-BigDecimal"><code>BigDecimal!</code></a> - </td> - <td> This price will override the current product price. </td> - </tr> - <tr> - <td data-property-name="minimumQuantity"> <code>minimumQuantity</code> - - <a href="#definition-Int"><code>Int!</code></a> - </td> - <td> Minimum item quantity that applies to this bulk pricing tier. </td> - </tr> - <tr> - <td data-property-name="maximumQuantity"> <code>maximumQuantity</code> - - <a href="#definition-Int"><code>Int</code></a> - </td> - <td> Maximum item quantity that applies to this bulk pricing tier - if not defined then the tier does not have an upper bound. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"price"</span>: BigDecimal, - <span class="hljs-attr">"minimumQuantity"</span>: <span class="hljs-number">123</span>, - <span class="hljs-attr">"maximumQuantity"</span>: <span class="hljs-number">123</span> -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-BulkPricingPercentageDiscount" class="definition panel" data-traverse-target="definition-BulkPricingPercentageDiscount"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/BulkPricingPercentageDiscount"></a> - <p><code>BulkPricingPercentageDiscount</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Bulk pricing tier that reduces the price of the product or variant by a percentage.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="percentOff"> <code>percentOff</code> - - <a href="#definition-BigDecimal"><code>BigDecimal!</code></a> - </td> - <td> The percentage that will be removed from the product price. </td> - </tr> - <tr> - <td data-property-name="minimumQuantity"> <code>minimumQuantity</code> - - <a href="#definition-Int"><code>Int!</code></a> - </td> - <td> Minimum item quantity that applies to this bulk pricing tier. </td> - </tr> - <tr> - <td data-property-name="maximumQuantity"> <code>maximumQuantity</code> - - <a href="#definition-Int"><code>Int</code></a> - </td> - <td> Maximum item quantity that applies to this bulk pricing tier - if not defined then the tier does not have an upper bound. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"percentOff"</span>: BigDecimal, - <span class="hljs-attr">"minimumQuantity"</span>: <span class="hljs-number">987</span>, - <span class="hljs-attr">"maximumQuantity"</span>: <span class="hljs-number">123</span> -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-BulkPricingRelativePriceDiscount" class="definition panel" data-traverse-target="definition-BulkPricingRelativePriceDiscount"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/BulkPricingRelativePriceDiscount"></a> - <p><code>BulkPricingRelativePriceDiscount</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Bulk pricing tier that will subtract an amount from the price of the product or variant.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="priceAdjustment"> <code>priceAdjustment</code> - - <a href="#definition-BigDecimal"><code>BigDecimal!</code></a> - </td> - <td> The price of the product/variant will be reduced by this priceAdjustment. </td> - </tr> - <tr> - <td data-property-name="minimumQuantity"> <code>minimumQuantity</code> - - <a href="#definition-Int"><code>Int!</code></a> - </td> - <td> Minimum item quantity that applies to this bulk pricing tier. </td> - </tr> - <tr> - <td data-property-name="maximumQuantity"> <code>maximumQuantity</code> - - <a href="#definition-Int"><code>Int</code></a> - </td> - <td> Maximum item quantity that applies to this bulk pricing tier - if not defined then the tier does not have an upper bound. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"priceAdjustment"</span>: BigDecimal, - <span class="hljs-attr">"minimumQuantity"</span>: <span class="hljs-number">987</span>, - <span class="hljs-attr">"maximumQuantity"</span>: <span class="hljs-number">123</span> -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-Category" class="definition panel" data-traverse-target="definition-Category"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/Category"></a> - <p><code>Category</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Category</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="id"> <code>id</code> - - <a href="#definition-ID"><code>ID!</code></a> - </td> - <td> The ID of an object </td> - </tr> - <tr> - <td data-property-name="entityId"> <code>entityId</code> - - <a href="#definition-Int"><code>Int!</code></a> - </td> - <td> Unique ID for the category. </td> - </tr> - <tr> - <td data-property-name="name"> <code>name</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Category name. </td> - </tr> - <tr> - <td data-property-name="path"> <code>path</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Category path. </td> - </tr> - <tr> - <td data-property-name="defaultImage"> <code>defaultImage</code> - - <a href="#definition-Image"><code>Image</code></a> - </td> - <td> Default image for the category. </td> - </tr> - <tr> - <td data-property-name="description"> <code>description</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Category description. </td> - </tr> - <tr> - <td data-property-name="breadcrumbs"> <code>breadcrumbs</code> - - <a href="#definition-BreadcrumbConnection"><code>BreadcrumbConnection!</code></a> - </td> - <td> Category breadcrumbs. </td> - </tr> - <tr> - <td colspan="2" class="no-top-border"> - <div class="field-arguments"> - <p class="field-arguments-header"> Arguments </p> - <div class="field-argument"> - <p class="field-argument-name"><code>depth</code> - - <a href="#definition-Int"><code>Int!</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>before</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>after</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>first</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>last</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - </div> - </td> - </tr> - <tr> - <td data-property-name="products"> <code>products</code> - - <a href="#definition-ProductConnection"><code>ProductConnection!</code></a> - </td> - <td> </td> - </tr> - <tr> - <td colspan="2" class="no-top-border"> - <div class="field-arguments"> - <p class="field-arguments-header"> Arguments </p> - <div class="field-argument"> - <p class="field-argument-name"><code>before</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>after</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>first</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>last</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>hideOutOfStock</code> - - <a href="#definition-Boolean"><code>Boolean</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>sortBy</code> - - <a href="#definition-CategoryProductSort"><code>CategoryProductSort</code></a> - </p> - </div> - </div> - </td> - </tr> - <tr> - <td data-property-name="metafields"> <code>metafields</code> - - <a href="#definition-MetafieldConnection"><code>MetafieldConnection!</code></a> - </td> - <td> Metafield data related to a category. </td> - </tr> - <tr> - <td colspan="2" class="no-top-border"> - <div class="field-arguments"> - <p class="field-arguments-header"> Arguments </p> - <div class="field-argument"> - <p class="field-argument-name"><code>namespace</code> - - <a href="#definition-String"><code>String!</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>keys</code> - - <a href="#definition-String"><code>[String!]</code></a> default = <code>[]</code></p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>before</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>after</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>first</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>last</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - </div> - </td> - </tr> - <tr> - <td data-property-name="seo"> <code>seo</code> - - <a href="#definition-SeoDetails"><code>SeoDetails!</code></a> - </td> - <td> Category SEO details. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"id"</span>: ID, - <span class="hljs-attr">"entityId"</span>: <span class="hljs-number">123</span>, - <span class="hljs-attr">"name"</span>: <span class="hljs-string">"abc123"</span>, - <span class="hljs-attr">"path"</span>: <span class="hljs-string">"abc123"</span>, - <span class="hljs-attr">"defaultImage"</span>: Image, - <span class="hljs-attr">"description"</span>: <span class="hljs-string">"xyz789"</span>, - <span class="hljs-attr">"breadcrumbs"</span>: BreadcrumbConnection, - <span class="hljs-attr">"products"</span>: ProductConnection, - <span class="hljs-attr">"metafields"</span>: MetafieldConnection, - <span class="hljs-attr">"seo"</span>: SeoDetails -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-CategoryConnection" class="definition panel" data-traverse-target="definition-CategoryConnection"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/CategoryConnection"></a> - <p><code>CategoryConnection</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>A connection to a list of items.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="pageInfo"> <code>pageInfo</code> - - <a href="#definition-PageInfo"><code>PageInfo!</code></a> - </td> - <td> Information to aid in pagination. </td> - </tr> - <tr> - <td data-property-name="edges"> <code>edges</code> - - <a href="#definition-CategoryEdge"><code>[CategoryEdge]</code></a> - </td> - <td> A list of edges. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"pageInfo"</span>: PageInfo, - <span class="hljs-attr">"edges"</span>: [CategoryEdge] -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-CategoryEdge" class="definition panel" data-traverse-target="definition-CategoryEdge"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/CategoryEdge"></a> - <p><code>CategoryEdge</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>An edge in a connection.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="node"> <code>node</code> - - <a href="#definition-Category"><code>Category!</code></a> - </td> - <td> The item at the end of the edge. </td> - </tr> - <tr> - <td data-property-name="cursor"> <code>cursor</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> A cursor for use in pagination. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"node"</span>: Category, <span class="hljs-attr">"cursor"</span>: <span class="hljs-string">"xyz789"</span>} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-CategoryProductSort" class="definition panel" data-traverse-target="definition-CategoryProductSort"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/CategoryProductSort"></a> - <p><code>CategoryProductSort</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Product sorting by categories.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Enum Value</th> - <th>Description</th> - </tr> - <tr> - <td> - <p><code>DEFAULT</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>FEATURED</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>NEWEST</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BEST_SELLING</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>A_TO_Z</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>Z_TO_A</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BEST_REVIEWED</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>LOWEST_PRICE</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>HIGHEST_PRICE</code></p> - </td> - <td> </td> - </tr> - </table> - </section> - </div> - </div> - </div> - <div id="definition-CategoryTreeItem" class="definition panel" data-traverse-target="definition-CategoryTreeItem"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/CategoryTreeItem"></a> - <p><code>CategoryTreeItem</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>An item in a tree of categories.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="entityId"> <code>entityId</code> - - <a href="#definition-Int"><code>Int!</code></a> - </td> - <td> The id category. </td> - </tr> - <tr> - <td data-property-name="name"> <code>name</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> The name of category. </td> - </tr> - <tr> - <td data-property-name="path"> <code>path</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Path assigned to this category </td> - </tr> - <tr> - <td data-property-name="description"> <code>description</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> The description of this category. </td> - </tr> - <tr> - <td data-property-name="productCount"> <code>productCount</code> - - <a href="#definition-Int"><code>Int!</code></a> - </td> - <td> The number of products in this category. </td> - </tr> - <tr> - <td data-property-name="image"> <code>image</code> - - <a href="#definition-Image"><code>Image</code></a> - </td> - <td> The category image. </td> - </tr> - <tr> - <td data-property-name="children"> <code>children</code> - - <a href="#definition-CategoryTreeItem"><code>[CategoryTreeItem!]!</code></a> - </td> - <td> Subcategories of this category </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"entityId"</span>: <span class="hljs-number">987</span>, - <span class="hljs-attr">"name"</span>: <span class="hljs-string">"xyz789"</span>, - <span class="hljs-attr">"path"</span>: <span class="hljs-string">"abc123"</span>, - <span class="hljs-attr">"description"</span>: <span class="hljs-string">"abc123"</span>, - <span class="hljs-attr">"productCount"</span>: <span class="hljs-number">123</span>, - <span class="hljs-attr">"image"</span>: Image, - <span class="hljs-attr">"children"</span>: [CategoryTreeItem] -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-CheckboxOption" class="definition panel" data-traverse-target="definition-CheckboxOption"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/CheckboxOption"></a> - <p><code>CheckboxOption</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>A simple yes/no question represented by a checkbox.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="checkedByDefault"> <code>checkedByDefault</code> - - <a href="#definition-Boolean"><code>Boolean!</code></a> - </td> - <td> Indicates the default checked status. </td> - </tr> - <tr> - <td data-property-name="entityId"> <code>entityId</code> - - <a href="#definition-Int"><code>Int!</code></a> - </td> - <td> Unique ID for the option. </td> - </tr> - <tr> - <td data-property-name="displayName"> <code>displayName</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Display name for the option. </td> - </tr> - <tr> - <td data-property-name="isRequired"> <code>isRequired</code> - - <a href="#definition-Boolean"><code>Boolean!</code></a> - </td> - <td> One of the option values is required to be selected for the checkout. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"checkedByDefault"</span>: <span class="hljs-literal">true</span>, - <span class="hljs-attr">"entityId"</span>: <span class="hljs-number">987</span>, - <span class="hljs-attr">"displayName"</span>: <span class="hljs-string">"abc123"</span>, - <span class="hljs-attr">"isRequired"</span>: <span class="hljs-literal">true</span> -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-ContactField" class="definition panel" data-traverse-target="definition-ContactField"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/ContactField"></a> - <p><code>ContactField</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Contact field</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="address"> <code>address</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Store address line. </td> - </tr> - <tr> - <td data-property-name="country"> <code>country</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Store country. </td> - </tr> - <tr> - <td data-property-name="addressType"> <code>addressType</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Store address type. </td> - </tr> - <tr> - <td data-property-name="email"> <code>email</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Store email. </td> - </tr> - <tr> - <td data-property-name="phone"> <code>phone</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Store phone number. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"address"</span>: <span class="hljs-string">"abc123"</span>, - <span class="hljs-attr">"country"</span>: <span class="hljs-string">"abc123"</span>, - <span class="hljs-attr">"addressType"</span>: <span class="hljs-string">"abc123"</span>, - <span class="hljs-attr">"email"</span>: <span class="hljs-string">"xyz789"</span>, - <span class="hljs-attr">"phone"</span>: <span class="hljs-string">"abc123"</span> -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-Content" class="definition panel" data-traverse-target="definition-Content"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/Content"></a> - <p><code>Content</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>The page content.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="renderedRegionsByPageType"> <code>renderedRegionsByPageType</code> - - <a href="#definition-RenderedRegionsByPageType"><code>RenderedRegionsByPageType!</code></a> - </td> - <td> </td> - </tr> - <tr> - <td colspan="2" class="no-top-border"> - <div class="field-arguments"> - <p class="field-arguments-header"> Arguments </p> - <div class="field-argument"> - <p class="field-argument-name"><code>pageType</code> - - <a href="#definition-PageType"><code>PageType!</code></a> - </p> - </div> - </div> - </td> - </tr> - <tr> - <td data-property-name="renderedRegionsByPageTypeAndEntityId"> <code>renderedRegionsByPageTypeAndEntityId</code> - - <a href="#definition-RenderedRegionsByPageType"><code>RenderedRegionsByPageType!</code></a> - </td> - <td> </td> - </tr> - <tr> - <td colspan="2" class="no-top-border"> - <div class="field-arguments"> - <p class="field-arguments-header"> Arguments </p> - <div class="field-argument"> - <p class="field-argument-name"><code>entityId</code> - - <a href="#definition-Long"><code>Long!</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>entityPageType</code> - - <a href="#definition-EntityPageType"><code>EntityPageType!</code></a> - </p> - </div> - </div> - </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"renderedRegionsByPageType"</span>: RenderedRegionsByPageType, - <span class="hljs-attr">"renderedRegionsByPageTypeAndEntityId"</span>: RenderedRegionsByPageType -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-Currency" class="definition panel" data-traverse-target="definition-Currency"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/Currency"></a> - <p><code>Currency</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="entityId"> <code>entityId</code> - - <a href="#definition-Int"><code>Int!</code></a> - </td> - <td> Currency ID. </td> - </tr> - <tr> - <td data-property-name="code"> <code>code</code> - - <a href="#definition-currencyCode"><code>currencyCode!</code></a> - </td> - <td> Currency code. </td> - </tr> - <tr> - <td data-property-name="name"> <code>name</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Currency name. </td> - </tr> - <tr> - <td data-property-name="flagImage"> <code>flagImage</code> - - <a href="#definition-String"><code>String</code></a> - </td> - <td> Flag image URL. </td> - </tr> - <tr> - <td data-property-name="isActive"> <code>isActive</code> - - <a href="#definition-Boolean"><code>Boolean!</code></a> - </td> - <td> Indicates whether this currency is active. </td> - </tr> - <tr> - <td data-property-name="exchangeRate"> <code>exchangeRate</code> - - <a href="#definition-Float"><code>Float!</code></a> - </td> - <td> Exchange rate relative to default currency. </td> - </tr> - <tr> - <td data-property-name="isTransactional"> <code>isTransactional</code> - - <a href="#definition-Boolean"><code>Boolean!</code></a> - </td> - <td> Indicates whether this currency is transactional. </td> - </tr> - <tr> - <td data-property-name="display"> <code>display</code> - - <a href="#definition-CurrencyDisplay"><code>CurrencyDisplay!</code></a> - </td> - <td> Currency display settings. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"entityId"</span>: <span class="hljs-number">123</span>, - <span class="hljs-attr">"code"</span>: currencyCode, - <span class="hljs-attr">"name"</span>: <span class="hljs-string">"abc123"</span>, - <span class="hljs-attr">"flagImage"</span>: <span class="hljs-string">"xyz789"</span>, - <span class="hljs-attr">"isActive"</span>: <span class="hljs-literal">false</span>, - <span class="hljs-attr">"exchangeRate"</span>: <span class="hljs-number">123.45</span>, - <span class="hljs-attr">"isTransactional"</span>: <span class="hljs-literal">true</span>, - <span class="hljs-attr">"display"</span>: CurrencyDisplay -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-CurrencyConnection" class="definition panel" data-traverse-target="definition-CurrencyConnection"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/CurrencyConnection"></a> - <p><code>CurrencyConnection</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>A connection to a list of items.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="pageInfo"> <code>pageInfo</code> - - <a href="#definition-PageInfo"><code>PageInfo!</code></a> - </td> - <td> Information to aid in pagination. </td> - </tr> - <tr> - <td data-property-name="edges"> <code>edges</code> - - <a href="#definition-CurrencyEdge"><code>[CurrencyEdge]</code></a> - </td> - <td> A list of edges. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"pageInfo"</span>: PageInfo, - <span class="hljs-attr">"edges"</span>: [CurrencyEdge] -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-CurrencyDisplay" class="definition panel" data-traverse-target="definition-CurrencyDisplay"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/CurrencyDisplay"></a> - <p><code>CurrencyDisplay</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="symbol"> <code>symbol</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Currency symbol. </td> - </tr> - <tr> - <td data-property-name="symbolPlacement"> <code>symbolPlacement</code> - - <a href="#definition-CurrencySymbolPosition"><code>CurrencySymbolPosition!</code></a> - </td> - <td> Currency symbol. </td> - </tr> - <tr> - <td data-property-name="decimalToken"> <code>decimalToken</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Currency decimal token. </td> - </tr> - <tr> - <td data-property-name="thousandsToken"> <code>thousandsToken</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Currency thousands token. </td> - </tr> - <tr> - <td data-property-name="decimalPlaces"> <code>decimalPlaces</code> - - <a href="#definition-Int"><code>Int!</code></a> - </td> - <td> Currency decimal places. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"symbol"</span>: <span class="hljs-string">"abc123"</span>, - <span class="hljs-attr">"symbolPlacement"</span>: CurrencySymbolPosition, - <span class="hljs-attr">"decimalToken"</span>: <span class="hljs-string">"abc123"</span>, - <span class="hljs-attr">"thousandsToken"</span>: <span class="hljs-string">"xyz789"</span>, - <span class="hljs-attr">"decimalPlaces"</span>: <span class="hljs-number">987</span> -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-CurrencyEdge" class="definition panel" data-traverse-target="definition-CurrencyEdge"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/CurrencyEdge"></a> - <p><code>CurrencyEdge</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>An edge in a connection.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="node"> <code>node</code> - - <a href="#definition-Currency"><code>Currency!</code></a> - </td> - <td> The item at the end of the edge. </td> - </tr> - <tr> - <td data-property-name="cursor"> <code>cursor</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> A cursor for use in pagination. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"node"</span>: Currency, <span class="hljs-attr">"cursor"</span>: <span class="hljs-string">"abc123"</span>} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-CurrencySymbolPosition" class="definition panel" data-traverse-target="definition-CurrencySymbolPosition"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/CurrencySymbolPosition"></a> - <p><code>CurrencySymbolPosition</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Currency symbol position</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Enum Value</th> - <th>Description</th> - </tr> - <tr> - <td> - <p><code>LEFT</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>RIGHT</code></p> - </td> - <td> </td> - </tr> - </table> - </section> - </div> - </div> - </div> - <div id="definition-CustomField" class="definition panel" data-traverse-target="definition-CustomField"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/CustomField"></a> - <p><code>CustomField</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Custom field</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="entityId"> <code>entityId</code> - - <a href="#definition-Int"><code>Int!</code></a> - </td> - <td> Custom field id. </td> - </tr> - <tr> - <td data-property-name="name"> <code>name</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Name of the custom field. </td> - </tr> - <tr> - <td data-property-name="value"> <code>value</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Value of the custom field. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"entityId"</span>: <span class="hljs-number">123</span>, <span class="hljs-attr">"name"</span>: <span class="hljs-string">"xyz789"</span>, <span class="hljs-attr">"value"</span>: <span class="hljs-string">"abc123"</span>} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-CustomFieldConnection" class="definition panel" data-traverse-target="definition-CustomFieldConnection"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/CustomFieldConnection"></a> - <p><code>CustomFieldConnection</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>A connection to a list of items.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="pageInfo"> <code>pageInfo</code> - - <a href="#definition-PageInfo"><code>PageInfo!</code></a> - </td> - <td> Information to aid in pagination. </td> - </tr> - <tr> - <td data-property-name="edges"> <code>edges</code> - - <a href="#definition-CustomFieldEdge"><code>[CustomFieldEdge]</code></a> - </td> - <td> A list of edges. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"pageInfo"</span>: PageInfo, - <span class="hljs-attr">"edges"</span>: [CustomFieldEdge] -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-CustomFieldEdge" class="definition panel" data-traverse-target="definition-CustomFieldEdge"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/CustomFieldEdge"></a> - <p><code>CustomFieldEdge</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>An edge in a connection.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="node"> <code>node</code> - - <a href="#definition-CustomField"><code>CustomField!</code></a> - </td> - <td> The item at the end of the edge. </td> - </tr> - <tr> - <td data-property-name="cursor"> <code>cursor</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> A cursor for use in pagination. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"node"</span>: CustomField, <span class="hljs-attr">"cursor"</span>: <span class="hljs-string">"xyz789"</span>} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-Customer" class="definition panel" data-traverse-target="definition-Customer"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/Customer"></a> - <p><code>Customer</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>A customer that shops on a store</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="entityId"> <code>entityId</code> - - <a href="#definition-Int"><code>Int!</code></a> - </td> - <td> The ID of the customer. </td> - </tr> - <tr> - <td data-property-name="company"> <code>company</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> The company name of the customer. </td> - </tr> - <tr> - <td data-property-name="customerGroupId"> <code>customerGroupId</code> - - <a href="#definition-Int"><code>Int!</code></a> - </td> - <td> The customer group id of the customer. </td> - </tr> - <tr> - <td data-property-name="email"> <code>email</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> The email address of the customer. </td> - </tr> - <tr> - <td data-property-name="firstName"> <code>firstName</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> The first name of the customer. </td> - </tr> - <tr> - <td data-property-name="lastName"> <code>lastName</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> The last name of the customer. </td> - </tr> - <tr> - <td data-property-name="notes"> <code>notes</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> The notes of the customer. </td> - </tr> - <tr> - <td data-property-name="phone"> <code>phone</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> The phone number of the customer. </td> - </tr> - <tr> - <td data-property-name="taxExemptCategory"> <code>taxExemptCategory</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> The tax exempt category of the customer. </td> - </tr> - <tr> - <td data-property-name="addressCount"> <code>addressCount</code> - - <a href="#definition-Int"><code>Int!</code></a> - </td> - <td> Customer addresses count. </td> - </tr> - <tr> - <td data-property-name="attributeCount"> <code>attributeCount</code> - - <a href="#definition-Int"><code>Int!</code></a> - </td> - <td> Customer attributes count. </td> - </tr> - <tr> - <td data-property-name="storeCredit"> <code>storeCredit</code> - - <a href="#definition-Money"><code>[Money!]!</code></a> - </td> - <td> Customer store credit. </td> - </tr> - <tr> - <td data-property-name="attributes"> <code>attributes</code> - - <a href="#definition-CustomerAttributes"><code>CustomerAttributes!</code></a> - </td> - <td> Customer attributes. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"entityId"</span>: <span class="hljs-number">123</span>, - <span class="hljs-attr">"company"</span>: <span class="hljs-string">"abc123"</span>, - <span class="hljs-attr">"customerGroupId"</span>: <span class="hljs-number">987</span>, - <span class="hljs-attr">"email"</span>: <span class="hljs-string">"xyz789"</span>, - <span class="hljs-attr">"firstName"</span>: <span class="hljs-string">"abc123"</span>, - <span class="hljs-attr">"lastName"</span>: <span class="hljs-string">"abc123"</span>, - <span class="hljs-attr">"notes"</span>: <span class="hljs-string">"abc123"</span>, - <span class="hljs-attr">"phone"</span>: <span class="hljs-string">"abc123"</span>, - <span class="hljs-attr">"taxExemptCategory"</span>: <span class="hljs-string">"abc123"</span>, - <span class="hljs-attr">"addressCount"</span>: <span class="hljs-number">123</span>, - <span class="hljs-attr">"attributeCount"</span>: <span class="hljs-number">123</span>, - <span class="hljs-attr">"storeCredit"</span>: [Money], - <span class="hljs-attr">"attributes"</span>: CustomerAttributes -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-CustomerAttribute" class="definition panel" data-traverse-target="definition-CustomerAttribute"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/CustomerAttribute"></a> - <p><code>CustomerAttribute</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>A custom, store-specific attribute for a customer</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="entityId"> <code>entityId</code> - - <a href="#definition-Int"><code>Int!</code></a> - </td> - <td> The ID of the custom customer attribute </td> - </tr> - <tr> - <td data-property-name="value"> <code>value</code> - - <a href="#definition-String"><code>String</code></a> - </td> - <td> The value of the custom customer attribute </td> - </tr> - <tr> - <td data-property-name="name"> <code>name</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> The name of the custom customer attribute </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"entityId"</span>: <span class="hljs-number">987</span>, <span class="hljs-attr">"value"</span>: <span class="hljs-string">"xyz789"</span>, <span class="hljs-attr">"name"</span>: <span class="hljs-string">"xyz789"</span>} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-CustomerAttributes" class="definition panel" data-traverse-target="definition-CustomerAttributes"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/CustomerAttributes"></a> - <p><code>CustomerAttributes</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Custom, store-specific customer attributes</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="attribute"> <code>attribute</code> - - <a href="#definition-CustomerAttribute"><code>CustomerAttribute!</code></a> - </td> - <td> </td> - </tr> - <tr> - <td colspan="2" class="no-top-border"> - <div class="field-arguments"> - <p class="field-arguments-header"> Arguments </p> - <div class="field-argument"> - <p class="field-argument-name"><code>entityId</code> - - <a href="#definition-Int"><code>Int!</code></a> - </p> - <p> - <p>The ID of the customer attribute</p> - </p> - </div> - </div> - </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"attribute"</span>: CustomerAttribute} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-DateFieldOption" class="definition panel" data-traverse-target="definition-DateFieldOption"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/DateFieldOption"></a> - <p><code>DateFieldOption</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>A calendar for allowing selection of a date.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="entityId"> <code>entityId</code> - - <a href="#definition-Int"><code>Int!</code></a> - </td> - <td> Unique ID for the option. </td> - </tr> - <tr> - <td data-property-name="displayName"> <code>displayName</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Display name for the option. </td> - </tr> - <tr> - <td data-property-name="isRequired"> <code>isRequired</code> - - <a href="#definition-Boolean"><code>Boolean!</code></a> - </td> - <td> One of the option values is required to be selected for the checkout. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"entityId"</span>: <span class="hljs-number">123</span>, <span class="hljs-attr">"displayName"</span>: <span class="hljs-string">"xyz789"</span>, <span class="hljs-attr">"isRequired"</span>: <span class="hljs-literal">true</span>} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-DateTime" class="definition panel" data-traverse-target="definition-DateTime"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/DateTime"></a> - <p><code>DateTime</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-gql"><span class="hljs-symbol">object</span> -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-DateTimeExtended" class="definition panel" data-traverse-target="definition-DateTimeExtended"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/DateTimeExtended"></a> - <p><code>DateTimeExtended</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Date Time Extended</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="utc"> <code>utc</code> - - <a href="#definition-DateTime"><code>DateTime!</code></a> - </td> - <td> ISO-8601 formatted date in UTC </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"utc"</span>: DateTime} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-DisplayField" class="definition panel" data-traverse-target="definition-DisplayField"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/DisplayField"></a> - <p><code>DisplayField</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Display field</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="shortDateFormat"> <code>shortDateFormat</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Short date format. </td> - </tr> - <tr> - <td data-property-name="extendedDateFormat"> <code>extendedDateFormat</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Extended date format. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"shortDateFormat"</span>: <span class="hljs-string">"abc123"</span>, <span class="hljs-attr">"extendedDateFormat"</span>: <span class="hljs-string">"abc123"</span>} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-Distance" class="definition panel" data-traverse-target="definition-Distance"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/Distance"></a> - <p><code>Distance</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Distance</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="value"> <code>value</code> - - <a href="#definition-Float"><code>Float!</code></a> - </td> - <td> Distance in specified length unit </td> - </tr> - <tr> - <td data-property-name="lengthUnit"> <code>lengthUnit</code> - - <a href="#definition-LengthUnit"><code>LengthUnit!</code></a> - </td> - <td> Length unit </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"value"</span>: <span class="hljs-number">123.45</span>, <span class="hljs-attr">"lengthUnit"</span>: LengthUnit} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-DistanceFilter" class="definition panel" data-traverse-target="definition-DistanceFilter"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/DistanceFilter"></a> - <p><code>DistanceFilter</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Filter locations by the distance</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Input Field</th> - <th>Description</th> - </tr> - <tr> - <td><code>radius</code> - - <a href="#definition-Float"><code>Float!</code></a> - </td> - <td> - <p>Radius of search in length units specified in lengthUnit argument</p> - </td> - </tr> - <tr> - <td><code>longitude</code> - - <a href="#definition-Float"><code>Float!</code></a> - </td> - <td> - <p>Signed decimal degrees without compass direction</p> - </td> - </tr> - <tr> - <td><code>latitude</code> - - <a href="#definition-Float"><code>Float!</code></a> - </td> - <td> - <p>Signed decimal degrees without compass direction</p> - </td> - </tr> - <tr> - <td><code>lengthUnit</code> - - <a href="#definition-LengthUnit"><code>LengthUnit!</code></a> - </td> - <td> </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"radius"</span>: <span class="hljs-number">123.45</span>, - <span class="hljs-attr">"longitude"</span>: <span class="hljs-number">987.65</span>, - <span class="hljs-attr">"latitude"</span>: <span class="hljs-number">987.65</span>, - <span class="hljs-attr">"lengthUnit"</span>: LengthUnit -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-EntityPageType" class="definition panel" data-traverse-target="definition-EntityPageType"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/EntityPageType"></a> - <p><code>EntityPageType</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Entity page type</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Enum Value</th> - <th>Description</th> - </tr> - <tr> - <td> - <p><code>BLOG_POST</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BRAND</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>CATEGORY</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>CONTACT_US</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>PAGE</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>PRODUCT</code></p> - </td> - <td> </td> - </tr> - </table> - </section> - </div> - </div> - </div> - <div id="definition-FileUploadFieldOption" class="definition panel" data-traverse-target="definition-FileUploadFieldOption"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/FileUploadFieldOption"></a> - <p><code>FileUploadFieldOption</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>A form allowing selection and uploading of a file from the user's local computer.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="entityId"> <code>entityId</code> - - <a href="#definition-Int"><code>Int!</code></a> - </td> - <td> Unique ID for the option. </td> - </tr> - <tr> - <td data-property-name="displayName"> <code>displayName</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Display name for the option. </td> - </tr> - <tr> - <td data-property-name="isRequired"> <code>isRequired</code> - - <a href="#definition-Boolean"><code>Boolean!</code></a> - </td> - <td> One of the option values is required to be selected for the checkout. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"entityId"</span>: <span class="hljs-number">123</span>, <span class="hljs-attr">"displayName"</span>: <span class="hljs-string">"xyz789"</span>, <span class="hljs-attr">"isRequired"</span>: <span class="hljs-literal">false</span>} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-Float" class="definition panel" data-traverse-target="definition-Float"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/Float"></a> - <p><code>Float</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>The <code>Float</code> scalar type represents signed double-precision fractional values as specified by - <a href="http://en.wikipedia.org/wiki/IEEE_floating_point">IEEE 754</a>.</p> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-gql"><span class="hljs-symbol">987.65</span> -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-ID" class="definition panel" data-traverse-target="definition-ID"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/ID"></a> - <p><code>ID</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>The <code>ID</code> scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as <code>"4"</code>) or integer (such as <code>4</code>) input value will be accepted as an ID.</p> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-gql"><span class="hljs-symbol">object</span> -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-Image" class="definition panel" data-traverse-target="definition-Image"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/Image"></a> - <p><code>Image</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Image</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="url"> <code>url</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Absolute path to image using store CDN. </td> - </tr> - <tr> - <td colspan="2" class="no-top-border"> - <div class="field-arguments"> - <p class="field-arguments-header"> Arguments </p> - <div class="field-argument"> - <p class="field-argument-name"><code>width</code> - - <a href="#definition-Int"><code>Int!</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>height</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - </div> - </td> - </tr> - <tr> - <td data-property-name="urlOriginal"> <code>urlOriginal</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Absolute path to original image using store CDN. </td> - </tr> - <tr> - <td data-property-name="altText"> <code>altText</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Text description of an image that can be used for SEO and/or accessibility purposes. </td> - </tr> - <tr> - <td data-property-name="isDefault"> <code>isDefault</code> - - <a href="#definition-Boolean"><code>Boolean!</code></a> - </td> - <td> Indicates whether this is the primary image. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"url"</span>: <span class="hljs-string">"xyz789"</span>, - <span class="hljs-attr">"urlOriginal"</span>: <span class="hljs-string">"xyz789"</span>, - <span class="hljs-attr">"altText"</span>: <span class="hljs-string">"xyz789"</span>, - <span class="hljs-attr">"isDefault"</span>: <span class="hljs-literal">true</span> -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-ImageConnection" class="definition panel" data-traverse-target="definition-ImageConnection"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/ImageConnection"></a> - <p><code>ImageConnection</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>A connection to a list of items.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="pageInfo"> <code>pageInfo</code> - - <a href="#definition-PageInfo"><code>PageInfo!</code></a> - </td> - <td> Information to aid in pagination. </td> - </tr> - <tr> - <td data-property-name="edges"> <code>edges</code> - - <a href="#definition-ImageEdge"><code>[ImageEdge]</code></a> - </td> - <td> A list of edges. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"pageInfo"</span>: PageInfo, - <span class="hljs-attr">"edges"</span>: [ImageEdge] -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-ImageEdge" class="definition panel" data-traverse-target="definition-ImageEdge"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/ImageEdge"></a> - <p><code>ImageEdge</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>An edge in a connection.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="node"> <code>node</code> - - <a href="#definition-Image"><code>Image!</code></a> - </td> - <td> The item at the end of the edge. </td> - </tr> - <tr> - <td data-property-name="cursor"> <code>cursor</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> A cursor for use in pagination. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"node"</span>: Image, <span class="hljs-attr">"cursor"</span>: <span class="hljs-string">"xyz789"</span>} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-Int" class="definition panel" data-traverse-target="definition-Int"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/Int"></a> - <p><code>Int</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>The <code>Int</code> scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.</p> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-gql"><span class="hljs-symbol">987</span> -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-Inventory" class="definition panel" data-traverse-target="definition-Inventory"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/Inventory"></a> - <p><code>Inventory</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>An inventory</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="locations"> <code>locations</code> - - <a href="#definition-LocationConnection"><code>LocationConnection!</code></a> - </td> - <td> Locations </td> - </tr> - <tr> - <td colspan="2" class="no-top-border"> - <div class="field-arguments"> - <p class="field-arguments-header"> Arguments </p> - <div class="field-argument"> - <p class="field-argument-name"><code>entityIds</code> - - <a href="#definition-Int"><code>[Int!]</code></a> default = <code>[]</code></p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>codes</code> - - <a href="#definition-String"><code>[String!]</code></a> default = <code>[]</code></p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>typeIds</code> - - <a href="#definition-String"><code>[String!]</code></a> default = <code>[]</code></p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>serviceTypeIds</code> - - <a href="#definition-String"><code>[String!]</code></a> default = <code>[]</code></p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>distanceFilter</code> - - <a href="#definition-DistanceFilter"><code>DistanceFilter</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>countryCodes</code> - - <a href="#definition-countryCode"><code>[countryCode!]</code></a> default = <code>[]</code></p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>states</code> - - <a href="#definition-String"><code>[String!]</code></a> default = <code>[]</code></p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>cities</code> - - <a href="#definition-String"><code>[String!]</code></a> default = <code>[]</code></p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>before</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>after</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>first</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>last</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - </div> - </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"locations"</span>: LocationConnection} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-InventoryByLocations" class="definition panel" data-traverse-target="definition-InventoryByLocations"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/InventoryByLocations"></a> - <p><code>InventoryByLocations</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Inventory By Locations</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="locationEntityId"> <code>locationEntityId</code> - - <a href="#definition-Long"><code>Long!</code></a> - </td> - <td> Location id. </td> - </tr> - <tr> - <td data-property-name="availableToSell"> <code>availableToSell</code> - - <a href="#definition-Long"><code>Long!</code></a> - </td> - <td> Number of available products in stock. </td> - </tr> - <tr> - <td data-property-name="warningLevel"> <code>warningLevel</code> - - <a href="#definition-Int"><code>Int!</code></a> - </td> - <td> Indicates a threshold low-stock level. </td> - </tr> - <tr> - <td data-property-name="isInStock"> <code>isInStock</code> - - <a href="#definition-Boolean"><code>Boolean!</code></a> - </td> - <td> Indicates whether this product is in stock. </td> - </tr> - <tr> - <td data-property-name="locationDistance"> <code>locationDistance</code> - - <a href="#definition-Distance"><code>Distance</code></a> - </td> - <td> Distance between location and specified longitude and latitude </td> - </tr> - <tr> - <td data-property-name="locationEntityTypeId"> <code>locationEntityTypeId</code> - - <a href="#definition-String"><code>String</code></a> - </td> - <td> Location type id. </td> - </tr> - <tr> - <td data-property-name="locationEntityServiceTypeIds" class="swagger-operation-deprecated"> <code>locationEntityServiceTypeIds</code> - - <a href="#definition-String"><code>[String!]!</code></a> - </td> - <td> Location service type ids. - <span class="properties-deprecation-reason">Deprecated. Will be substituted with pickup methods.</span> - </td> - </tr> - <tr> - <td data-property-name="locationEntityCode"> <code>locationEntityCode</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Location code. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"locationEntityId"</span>: Long, - <span class="hljs-attr">"availableToSell"</span>: Long, - <span class="hljs-attr">"warningLevel"</span>: <span class="hljs-number">123</span>, - <span class="hljs-attr">"isInStock"</span>: <span class="hljs-literal">false</span>, - <span class="hljs-attr">"locationDistance"</span>: Distance, - <span class="hljs-attr">"locationEntityTypeId"</span>: <span class="hljs-string">"abc123"</span>, - <span class="hljs-attr">"locationEntityServiceTypeIds"</span>: [<span class="hljs-string">"abc123"</span>], - <span class="hljs-attr">"locationEntityCode"</span>: <span class="hljs-string">"abc123"</span> -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-LengthUnit" class="definition panel" data-traverse-target="definition-LengthUnit"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/LengthUnit"></a> - <p><code>LengthUnit</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>length unit</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Enum Value</th> - <th>Description</th> - </tr> - <tr> - <td> - <p><code>Miles</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>Kilometres</code></p> - </td> - <td> </td> - </tr> - </table> - </section> - </div> - </div> - </div> - <div id="definition-LocationConnection" class="definition panel" data-traverse-target="definition-LocationConnection"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/LocationConnection"></a> - <p><code>LocationConnection</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>A connection to a list of items.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="pageInfo"> <code>pageInfo</code> - - <a href="#definition-PageInfo"><code>PageInfo!</code></a> - </td> - <td> Information to aid in pagination. </td> - </tr> - <tr> - <td data-property-name="edges"> <code>edges</code> - - <a href="#definition-LocationEdge"><code>[LocationEdge]</code></a> - </td> - <td> A list of edges. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"pageInfo"</span>: PageInfo, - <span class="hljs-attr">"edges"</span>: [LocationEdge] -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-LocationEdge" class="definition panel" data-traverse-target="definition-LocationEdge"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/LocationEdge"></a> - <p><code>LocationEdge</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>An edge in a connection.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="node"> <code>node</code> - - <a href="#definition-InventoryByLocations"><code>InventoryByLocations!</code></a> - </td> - <td> The item at the end of the edge. </td> - </tr> - <tr> - <td data-property-name="cursor"> <code>cursor</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> A cursor for use in pagination. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"node"</span>: InventoryByLocations, <span class="hljs-attr">"cursor"</span>: <span class="hljs-string">"abc123"</span>} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-LoginResult" class="definition panel" data-traverse-target="definition-LoginResult"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/LoginResult"></a> - <p><code>LoginResult</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Login result</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="result" class="swagger-operation-deprecated"> <code>result</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> The result of a login - <span class="properties-deprecation-reason">Use customer node instead.</span> - </td> - </tr> - <tr> - <td data-property-name="customer"> <code>customer</code> - - <a href="#definition-Customer"><code>Customer</code></a> - </td> - <td> The currently logged in customer. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"result"</span>: <span class="hljs-string">"abc123"</span>, <span class="hljs-attr">"customer"</span>: Customer} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-LogoField" class="definition panel" data-traverse-target="definition-LogoField"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/LogoField"></a> - <p><code>LogoField</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Logo field</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="title"> <code>title</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Logo title. </td> - </tr> - <tr> - <td data-property-name="image"> <code>image</code> - - <a href="#definition-Image"><code>Image!</code></a> - </td> - <td> Store logo image. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"title"</span>: <span class="hljs-string">"xyz789"</span>, <span class="hljs-attr">"image"</span>: Image} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-LogoutResult" class="definition panel" data-traverse-target="definition-LogoutResult"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/LogoutResult"></a> - <p><code>LogoutResult</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Logout result</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="result"> <code>result</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> The result of a logout </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"result"</span>: <span class="hljs-string">"abc123"</span>} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-Long" class="definition panel" data-traverse-target="definition-Long"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/Long"></a> - <p><code>Long</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>The <code>Long</code> scalar type represents non-fractional signed whole numeric values. Long can represent values between -(2^63) and 2^63 - 1.</p> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-gql"><span class="hljs-symbol">object</span> -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-Measurement" class="definition panel" data-traverse-target="definition-Measurement"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/Measurement"></a> - <p><code>Measurement</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Measurement</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="value"> <code>value</code> - - <a href="#definition-Float"><code>Float!</code></a> - </td> - <td> Unformatted weight measurement value. </td> - </tr> - <tr> - <td data-property-name="unit"> <code>unit</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Unit of measurement. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"value"</span>: <span class="hljs-number">987.65</span>, <span class="hljs-attr">"unit"</span>: <span class="hljs-string">"abc123"</span>} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-MetafieldConnection" class="definition panel" data-traverse-target="definition-MetafieldConnection"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/MetafieldConnection"></a> - <p><code>MetafieldConnection</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>A connection to a list of items.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="pageInfo"> <code>pageInfo</code> - - <a href="#definition-PageInfo"><code>PageInfo!</code></a> - </td> - <td> Information to aid in pagination. </td> - </tr> - <tr> - <td data-property-name="edges"> <code>edges</code> - - <a href="#definition-MetafieldEdge"><code>[MetafieldEdge]</code></a> - </td> - <td> A list of edges. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"pageInfo"</span>: PageInfo, - <span class="hljs-attr">"edges"</span>: [MetafieldEdge] -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-MetafieldEdge" class="definition panel" data-traverse-target="definition-MetafieldEdge"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/MetafieldEdge"></a> - <p><code>MetafieldEdge</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>An edge in a connection.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="node"> <code>node</code> - - <a href="#definition-Metafields"><code>Metafields!</code></a> - </td> - <td> The item at the end of the edge. </td> - </tr> - <tr> - <td data-property-name="cursor"> <code>cursor</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> A cursor for use in pagination. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"node"</span>: Metafields, <span class="hljs-attr">"cursor"</span>: <span class="hljs-string">"abc123"</span>} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-Metafields" class="definition panel" data-traverse-target="definition-Metafields"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/Metafields"></a> - <p><code>Metafields</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Key/Value pairs of data attached tied to a resource entity (product, brand, category, etc.)</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="id"> <code>id</code> - - <a href="#definition-ID"><code>ID!</code></a> - </td> - <td> The ID of an object </td> - </tr> - <tr> - <td data-property-name="entityId"> <code>entityId</code> - - <a href="#definition-Int"><code>Int!</code></a> - </td> - <td> The ID of the metafield when referencing via our backend API. </td> - </tr> - <tr> - <td data-property-name="key"> <code>key</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> A label for identifying a metafield data value. </td> - </tr> - <tr> - <td data-property-name="value"> <code>value</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> A metafield value. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"id"</span>: ID, - <span class="hljs-attr">"entityId"</span>: <span class="hljs-number">987</span>, - <span class="hljs-attr">"key"</span>: <span class="hljs-string">"abc123"</span>, - <span class="hljs-attr">"value"</span>: <span class="hljs-string">"abc123"</span> -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-Money" class="definition panel" data-traverse-target="definition-Money"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/Money"></a> - <p><code>Money</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>A money object - includes currency code and a money amount</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="currencyCode"> <code>currencyCode</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Currency code of the current money. </td> - </tr> - <tr> - <td data-property-name="value"> <code>value</code> - - <a href="#definition-BigDecimal"><code>BigDecimal!</code></a> - </td> - <td> The amount of money. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"currencyCode"</span>: <span class="hljs-string">"abc123"</span>, <span class="hljs-attr">"value"</span>: BigDecimal} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-MoneyRange" class="definition panel" data-traverse-target="definition-MoneyRange"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/MoneyRange"></a> - <p><code>MoneyRange</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>A min and max pair of money objects</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="min"> <code>min</code> - - <a href="#definition-Money"><code>Money!</code></a> - </td> - <td> Minimum money object. </td> - </tr> - <tr> - <td data-property-name="max"> <code>max</code> - - <a href="#definition-Money"><code>Money!</code></a> - </td> - <td> Maximum money object. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"min"</span>: Money, <span class="hljs-attr">"max"</span>: Money} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-MultiLineTextFieldOption" class="definition panel" data-traverse-target="definition-MultiLineTextFieldOption"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/MultiLineTextFieldOption"></a> - <p><code>MultiLineTextFieldOption</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>A multi-line text input field, aka a text box.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="entityId"> <code>entityId</code> - - <a href="#definition-Int"><code>Int!</code></a> - </td> - <td> Unique ID for the option. </td> - </tr> - <tr> - <td data-property-name="displayName"> <code>displayName</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Display name for the option. </td> - </tr> - <tr> - <td data-property-name="isRequired"> <code>isRequired</code> - - <a href="#definition-Boolean"><code>Boolean!</code></a> - </td> - <td> One of the option values is required to be selected for the checkout. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"entityId"</span>: <span class="hljs-number">123</span>, <span class="hljs-attr">"displayName"</span>: <span class="hljs-string">"abc123"</span>, <span class="hljs-attr">"isRequired"</span>: <span class="hljs-literal">false</span>} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-MultipleChoiceOption" class="definition panel" data-traverse-target="definition-MultipleChoiceOption"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/MultipleChoiceOption"></a> - <p><code>MultipleChoiceOption</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>An option type that has a fixed list of values.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="displayStyle"> <code>displayStyle</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> The chosen display style for this multiple choice option. </td> - </tr> - <tr> - <td data-property-name="values"> <code>values</code> - - <a href="#definition-ProductOptionValueConnection"><code>ProductOptionValueConnection!</code></a> - </td> - <td> List of option values. </td> - </tr> - <tr> - <td colspan="2" class="no-top-border"> - <div class="field-arguments"> - <p class="field-arguments-header"> Arguments </p> - <div class="field-argument"> - <p class="field-argument-name"><code>before</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>after</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>first</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>last</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - </div> - </td> - </tr> - <tr> - <td data-property-name="entityId"> <code>entityId</code> - - <a href="#definition-Int"><code>Int!</code></a> - </td> - <td> Unique ID for the option. </td> - </tr> - <tr> - <td data-property-name="displayName"> <code>displayName</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Display name for the option. </td> - </tr> - <tr> - <td data-property-name="isRequired"> <code>isRequired</code> - - <a href="#definition-Boolean"><code>Boolean!</code></a> - </td> - <td> One of the option values is required to be selected for the checkout. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"displayStyle"</span>: <span class="hljs-string">"xyz789"</span>, - <span class="hljs-attr">"values"</span>: ProductOptionValueConnection, - <span class="hljs-attr">"entityId"</span>: <span class="hljs-number">987</span>, - <span class="hljs-attr">"displayName"</span>: <span class="hljs-string">"xyz789"</span>, - <span class="hljs-attr">"isRequired"</span>: <span class="hljs-literal">false</span> -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-MultipleChoiceOptionValue" class="definition panel" data-traverse-target="definition-MultipleChoiceOptionValue"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/MultipleChoiceOptionValue"></a> - <p><code>MultipleChoiceOptionValue</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>A simple multiple choice value comprised of an id and a label.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="entityId"> <code>entityId</code> - - <a href="#definition-Int"><code>Int!</code></a> - </td> - <td> Unique ID for the option value. </td> - </tr> - <tr> - <td data-property-name="label"> <code>label</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Label for the option value. </td> - </tr> - <tr> - <td data-property-name="isDefault"> <code>isDefault</code> - - <a href="#definition-Boolean"><code>Boolean!</code></a> - </td> - <td> Indicates whether this value is the chosen default selected value. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"entityId"</span>: <span class="hljs-number">123</span>, <span class="hljs-attr">"label"</span>: <span class="hljs-string">"abc123"</span>, <span class="hljs-attr">"isDefault"</span>: <span class="hljs-literal">false</span>} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-NumberFieldOption" class="definition panel" data-traverse-target="definition-NumberFieldOption"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/NumberFieldOption"></a> - <p><code>NumberFieldOption</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>A single line text input field that only accepts numbers.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="entityId"> <code>entityId</code> - - <a href="#definition-Int"><code>Int!</code></a> - </td> - <td> Unique ID for the option. </td> - </tr> - <tr> - <td data-property-name="displayName"> <code>displayName</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Display name for the option. </td> - </tr> - <tr> - <td data-property-name="isRequired"> <code>isRequired</code> - - <a href="#definition-Boolean"><code>Boolean!</code></a> - </td> - <td> One of the option values is required to be selected for the checkout. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"entityId"</span>: <span class="hljs-number">123</span>, <span class="hljs-attr">"displayName"</span>: <span class="hljs-string">"xyz789"</span>, <span class="hljs-attr">"isRequired"</span>: <span class="hljs-literal">true</span>} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-OptionConnection" class="definition panel" data-traverse-target="definition-OptionConnection"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/OptionConnection"></a> - <p><code>OptionConnection</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>A connection to a list of items.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="pageInfo"> <code>pageInfo</code> - - <a href="#definition-PageInfo"><code>PageInfo!</code></a> - </td> - <td> Information to aid in pagination. </td> - </tr> - <tr> - <td data-property-name="edges"> <code>edges</code> - - <a href="#definition-OptionEdge"><code>[OptionEdge]</code></a> - </td> - <td> A list of edges. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"pageInfo"</span>: PageInfo, - <span class="hljs-attr">"edges"</span>: [OptionEdge] -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-OptionEdge" class="definition panel" data-traverse-target="definition-OptionEdge"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/OptionEdge"></a> - <p><code>OptionEdge</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>An edge in a connection.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="node"> <code>node</code> - - <a href="#definition-ProductOption"><code>ProductOption!</code></a> - </td> - <td> The item at the end of the edge. </td> - </tr> - <tr> - <td data-property-name="cursor"> <code>cursor</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> A cursor for use in pagination. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"node"</span>: ProductOption, <span class="hljs-attr">"cursor"</span>: <span class="hljs-string">"xyz789"</span>} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-OptionValueConnection" class="definition panel" data-traverse-target="definition-OptionValueConnection"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/OptionValueConnection"></a> - <p><code>OptionValueConnection</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>A connection to a list of items.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="pageInfo"> <code>pageInfo</code> - - <a href="#definition-PageInfo"><code>PageInfo!</code></a> - </td> - <td> Information to aid in pagination. </td> - </tr> - <tr> - <td data-property-name="edges"> <code>edges</code> - - <a href="#definition-OptionValueEdge"><code>[OptionValueEdge]</code></a> - </td> - <td> A list of edges. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"pageInfo"</span>: PageInfo, - <span class="hljs-attr">"edges"</span>: [OptionValueEdge] -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-OptionValueEdge" class="definition panel" data-traverse-target="definition-OptionValueEdge"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/OptionValueEdge"></a> - <p><code>OptionValueEdge</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>An edge in a connection.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="node"> <code>node</code> - - <a href="#definition-ProductOptionValue"><code>ProductOptionValue!</code></a> - </td> - <td> The item at the end of the edge. </td> - </tr> - <tr> - <td data-property-name="cursor"> <code>cursor</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> A cursor for use in pagination. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"node"</span>: ProductOptionValue, <span class="hljs-attr">"cursor"</span>: <span class="hljs-string">"abc123"</span>} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-OptionValueId" class="definition panel" data-traverse-target="definition-OptionValueId"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/OptionValueId"></a> - <p><code>OptionValueId</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Input Field</th> - <th>Description</th> - </tr> - <tr> - <td><code>optionEntityId</code> - - <a href="#definition-Int"><code>Int!</code></a> - </td> - <td> </td> - </tr> - <tr> - <td><code>valueEntityId</code> - - <a href="#definition-Int"><code>Int!</code></a> - </td> - <td> </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"optionEntityId"</span>: <span class="hljs-number">987</span>, <span class="hljs-attr">"valueEntityId"</span>: <span class="hljs-number">987</span>} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-PageInfo" class="definition panel" data-traverse-target="definition-PageInfo"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/PageInfo"></a> - <p><code>PageInfo</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Information about pagination in a connection.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="hasNextPage"> <code>hasNextPage</code> - - <a href="#definition-Boolean"><code>Boolean!</code></a> - </td> - <td> When paginating forwards, are there more items? </td> - </tr> - <tr> - <td data-property-name="hasPreviousPage"> <code>hasPreviousPage</code> - - <a href="#definition-Boolean"><code>Boolean!</code></a> - </td> - <td> When paginating backwards, are there more items? </td> - </tr> - <tr> - <td data-property-name="startCursor"> <code>startCursor</code> - - <a href="#definition-String"><code>String</code></a> - </td> - <td> When paginating backwards, the cursor to continue. </td> - </tr> - <tr> - <td data-property-name="endCursor"> <code>endCursor</code> - - <a href="#definition-String"><code>String</code></a> - </td> - <td> When paginating forwards, the cursor to continue. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"hasNextPage"</span>: <span class="hljs-literal">true</span>, - <span class="hljs-attr">"hasPreviousPage"</span>: <span class="hljs-literal">false</span>, - <span class="hljs-attr">"startCursor"</span>: <span class="hljs-string">"abc123"</span>, - <span class="hljs-attr">"endCursor"</span>: <span class="hljs-string">"xyz789"</span> -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-PageType" class="definition panel" data-traverse-target="definition-PageType"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/PageType"></a> - <p><code>PageType</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Page type</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Enum Value</th> - <th>Description</th> - </tr> - <tr> - <td> - <p><code>ACCOUNT_ADDRESS</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ACCOUNT_ADD_ADDRESS</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ACCOUNT_ADD_RETURN</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ACCOUNT_ADD_WISHLIST</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ACCOUNT_DOWNLOAD_ITEM</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ACCOUNT_EDIT</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ACCOUNT_INBOX</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ACCOUNT_ORDERS_ALL</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ACCOUNT_ORDERS_COMPLETED</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ACCOUNT_ORDERS_DETAILS</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ACCOUNT_ORDERS_INVOICE</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ACCOUNT_RECENT_ITEMS</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ACCOUNT_RETURNS</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ACCOUNT_RETURN_SAVED</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ACCOUNT_WISHLISTS</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ACCOUNT_WISHLIST_DETAILS</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>AUTH_ACCOUNT_CREATED</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>AUTH_CREATE_ACC</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>AUTH_FORGOT_PASS</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>AUTH_LOGIN</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>AUTH_NEW_PASS</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BLOG</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BRANDS</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>CART</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>COMPARE</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>GIFT_CERT_BALANCE</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>GIFT_CERT_PURCHASE</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>GIFT_CERT_REDEEM</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>HOME</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ORDER_INFO</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>SEARCH</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>SITEMAP</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>SUBSCRIBED</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>UNSUBSCRIBE</code></p> - </td> - <td> </td> - </tr> - </table> - </section> - </div> - </div> - </div> - <div id="definition-PriceRanges" class="definition panel" data-traverse-target="definition-PriceRanges"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/PriceRanges"></a> - <p><code>PriceRanges</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>The min and max range of prices that apply to this product.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="priceRange"> <code>priceRange</code> - - <a href="#definition-MoneyRange"><code>MoneyRange!</code></a> - </td> - <td> Product price min/max range. </td> - </tr> - <tr> - <td data-property-name="retailPriceRange"> <code>retailPriceRange</code> - - <a href="#definition-MoneyRange"><code>MoneyRange</code></a> - </td> - <td> Product retail price min/max range. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"priceRange"</span>: MoneyRange, - <span class="hljs-attr">"retailPriceRange"</span>: MoneyRange -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-PriceSearchFilterInput" class="definition panel" data-traverse-target="definition-PriceSearchFilterInput"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/PriceSearchFilterInput"></a> - <p><code>PriceSearchFilterInput</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Input Field</th> - <th>Description</th> - </tr> - <tr> - <td><code>minPrice</code> - - <a href="#definition-Float"><code>Float</code></a> - </td> - <td> </td> - </tr> - <tr> - <td><code>maxPrice</code> - - <a href="#definition-Float"><code>Float</code></a> - </td> - <td> </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"minPrice"</span>: <span class="hljs-number">987.65</span>, <span class="hljs-attr">"maxPrice"</span>: <span class="hljs-number">987.65</span>} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-Prices" class="definition panel" data-traverse-target="definition-Prices"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/Prices"></a> - <p><code>Prices</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>The various prices that can be set on a product.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="price"> <code>price</code> - - <a href="#definition-Money"><code>Money!</code></a> - </td> - <td> Calculated price of the product. Calculated price takes into account basePrice, salePrice, rules (modifier, option, option set) that apply to the product configuration, and customer group discounts. It represents the in-cart price for a product configuration without bulk pricing rules. </td> - </tr> - <tr> - <td data-property-name="salePrice"> <code>salePrice</code> - - <a href="#definition-Money"><code>Money</code></a> - </td> - <td> Sale price of the product. </td> - </tr> - <tr> - <td data-property-name="basePrice"> <code>basePrice</code> - - <a href="#definition-Money"><code>Money</code></a> - </td> - <td> Original price of the product. </td> - </tr> - <tr> - <td data-property-name="retailPrice"> <code>retailPrice</code> - - <a href="#definition-Money"><code>Money</code></a> - </td> - <td> Retail price of the product. </td> - </tr> - <tr> - <td data-property-name="mapPrice"> <code>mapPrice</code> - - <a href="#definition-Money"><code>Money</code></a> - </td> - <td> Minimum advertised price of the product. </td> - </tr> - <tr> - <td data-property-name="priceRange"> <code>priceRange</code> - - <a href="#definition-MoneyRange"><code>MoneyRange!</code></a> - </td> - <td> Product price min/max range. </td> - </tr> - <tr> - <td data-property-name="retailPriceRange"> <code>retailPriceRange</code> - - <a href="#definition-MoneyRange"><code>MoneyRange</code></a> - </td> - <td> Product retail price min/max range. </td> - </tr> - <tr> - <td data-property-name="saved"> <code>saved</code> - - <a href="#definition-Money"><code>Money</code></a> - </td> - <td> The difference between the retail price (MSRP) and the current price, which can be presented to the shopper as their savings. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"price"</span>: Money, - <span class="hljs-attr">"salePrice"</span>: Money, - <span class="hljs-attr">"basePrice"</span>: Money, - <span class="hljs-attr">"retailPrice"</span>: Money, - <span class="hljs-attr">"mapPrice"</span>: Money, - <span class="hljs-attr">"priceRange"</span>: MoneyRange, - <span class="hljs-attr">"retailPriceRange"</span>: MoneyRange, - <span class="hljs-attr">"saved"</span>: Money -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-Product" class="definition panel" data-traverse-target="definition-Product"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/Product"></a> - <p><code>Product</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Product</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="id"> <code>id</code> - - <a href="#definition-ID"><code>ID!</code></a> - </td> - <td> The ID of an object </td> - </tr> - <tr> - <td data-property-name="entityId"> <code>entityId</code> - - <a href="#definition-Int"><code>Int!</code></a> - </td> - <td> Id of the product. </td> - </tr> - <tr> - <td data-property-name="sku"> <code>sku</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Default product variant when no options are selected. </td> - </tr> - <tr> - <td data-property-name="path"> <code>path</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Relative URL path to product page. </td> - </tr> - <tr> - <td data-property-name="name"> <code>name</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Name of the product. </td> - </tr> - <tr> - <td data-property-name="description"> <code>description</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Description of the product. </td> - </tr> - <tr> - <td data-property-name="plainTextDescription"> <code>plainTextDescription</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Description of the product in plain text. </td> - </tr> - <tr> - <td colspan="2" class="no-top-border"> - <div class="field-arguments"> - <p class="field-arguments-header"> Arguments </p> - <div class="field-argument"> - <p class="field-argument-name"><code>characterLimit</code> - - <a href="#definition-Int"><code>Int</code></a> default = <code>120</code></p> - </div> - </div> - </td> - </tr> - <tr> - <td data-property-name="warranty"> <code>warranty</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Warranty information of the product. </td> - </tr> - <tr> - <td data-property-name="minPurchaseQuantity"> <code>minPurchaseQuantity</code> - - <a href="#definition-Int"><code>Int</code></a> - </td> - <td> Minimum purchasable quantity for this product in a single order. </td> - </tr> - <tr> - <td data-property-name="maxPurchaseQuantity"> <code>maxPurchaseQuantity</code> - - <a href="#definition-Int"><code>Int</code></a> - </td> - <td> Maximum purchasable quantity for this product in a single order. </td> - </tr> - <tr> - <td data-property-name="addToCartUrl"> <code>addToCartUrl</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Absolute URL path for adding a product to cart. </td> - </tr> - <tr> - <td data-property-name="addToWishlistUrl" class="swagger-operation-deprecated"> <code>addToWishlistUrl</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Absolute URL path for adding a product to customer's wishlist. - <span class="properties-deprecation-reason">Deprecated.</span> - </td> - </tr> - <tr> - <td data-property-name="prices"> <code>prices</code> - - <a href="#definition-Prices"><code>Prices</code></a> - </td> - <td> Prices object determined by supplied product ID, variant ID, and selected option IDs. </td> - </tr> - <tr> - <td colspan="2" class="no-top-border"> - <div class="field-arguments"> - <p class="field-arguments-header"> Arguments </p> - <div class="field-argument"> - <p class="field-argument-name"><code>includeTax</code> - - <a href="#definition-Boolean"><code>Boolean</code></a> default = <code>false</code></p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>currencyCode</code> - - <a href="#definition-currencyCode"><code>currencyCode</code></a> - </p> - <p> - <p>Please select a currency</p> - </p> - </div> - </div> - </td> - </tr> - <tr> - <td data-property-name="priceRanges" class="swagger-operation-deprecated"> <code>priceRanges</code> - - <a href="#definition-PriceRanges"><code>PriceRanges</code></a> - </td> - <td> The minimum and maximum price of this product based on variant pricing and/or modifier price rules. - <span class="properties-deprecation-reason">Use priceRanges inside prices node instead.</span> - </td> - </tr> - <tr> - <td colspan="2" class="no-top-border"> - <div class="field-arguments"> - <p class="field-arguments-header"> Arguments </p> - <div class="field-argument"> - <p class="field-argument-name"><code>includeTax</code> - - <a href="#definition-Boolean"><code>Boolean</code></a> default = <code>false</code></p> - </div> - </div> - </td> - </tr> - <tr> - <td data-property-name="weight"> <code>weight</code> - - <a href="#definition-Measurement"><code>Measurement</code></a> - </td> - <td> Weight of the product. </td> - </tr> - <tr> - <td data-property-name="height"> <code>height</code> - - <a href="#definition-Measurement"><code>Measurement</code></a> - </td> - <td> Height of the product. </td> - </tr> - <tr> - <td data-property-name="width"> <code>width</code> - - <a href="#definition-Measurement"><code>Measurement</code></a> - </td> - <td> Width of the product. </td> - </tr> - <tr> - <td data-property-name="depth"> <code>depth</code> - - <a href="#definition-Measurement"><code>Measurement</code></a> - </td> - <td> Depth of the product. </td> - </tr> - <tr> - <td data-property-name="options"> <code>options</code> - - <a href="#definition-OptionConnection"><code>OptionConnection!</code></a> - </td> - <td> Product options. </td> - </tr> - <tr> - <td colspan="2" class="no-top-border"> - <div class="field-arguments"> - <p class="field-arguments-header"> Arguments </p> - <div class="field-argument"> - <p class="field-argument-name"><code>before</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>after</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>first</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>last</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - </div> - </td> - </tr> - <tr> - <td data-property-name="productOptions"> <code>productOptions</code> - - <a href="#definition-ProductOptionConnection"><code>ProductOptionConnection!</code></a> - </td> - <td> Product options. </td> - </tr> - <tr> - <td colspan="2" class="no-top-border"> - <div class="field-arguments"> - <p class="field-arguments-header"> Arguments </p> - <div class="field-argument"> - <p class="field-argument-name"><code>before</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>after</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>first</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>last</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - </div> - </td> - </tr> - <tr> - <td data-property-name="reviewSummary"> <code>reviewSummary</code> - - <a href="#definition-Reviews"><code>Reviews!</code></a> - </td> - <td> Summary of the product reviews, includes the total number of reviews submitted and summation of the ratings on the reviews (ratings range from 0-5 per review). </td> - </tr> - <tr> - <td data-property-name="type"> <code>type</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Type of product, ex: physical, digital </td> - </tr> - <tr> - <td data-property-name="availability" class="swagger-operation-deprecated"> <code>availability</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> The availability state of the product. - <span class="properties-deprecation-reason">Use status inside availabilityV2 instead.</span> - </td> - </tr> - <tr> - <td data-property-name="availabilityDescription" class="swagger-operation-deprecated"> <code>availabilityDescription</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> A few words telling the customer how long it will normally take to ship this product, such as 'Usually ships in 24 hours'. - <span class="properties-deprecation-reason">Use description inside availabilityV2 instead.</span> - </td> - </tr> - <tr> - <td data-property-name="categories"> <code>categories</code> - - <a href="#definition-CategoryConnection"><code>CategoryConnection!</code></a> - </td> - <td> List of categories associated with the product. </td> - </tr> - <tr> - <td colspan="2" class="no-top-border"> - <div class="field-arguments"> - <p class="field-arguments-header"> Arguments </p> - <div class="field-argument"> - <p class="field-argument-name"><code>before</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>after</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>first</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>last</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - </div> - </td> - </tr> - <tr> - <td data-property-name="brand"> <code>brand</code> - - <a href="#definition-Brand"><code>Brand</code></a> - </td> - <td> Brand associated with the product. </td> - </tr> - <tr> - <td data-property-name="variants"> <code>variants</code> - - <a href="#definition-VariantConnection"><code>VariantConnection!</code></a> - </td> - <td> Variants associated with the product. </td> - </tr> - <tr> - <td colspan="2" class="no-top-border"> - <div class="field-arguments"> - <p class="field-arguments-header"> Arguments </p> - <div class="field-argument"> - <p class="field-argument-name"><code>before</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>after</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>first</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>last</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>entityIds</code> - - <a href="#definition-Int"><code>[Int!]</code></a> default = <code>[]</code></p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>optionValueIds</code> - - <a href="#definition-OptionValueId"><code>[OptionValueId!]</code></a> default = <code>[]</code></p> - </div> - </div> - </td> - </tr> - <tr> - <td data-property-name="customFields"> <code>customFields</code> - - <a href="#definition-CustomFieldConnection"><code>CustomFieldConnection!</code></a> - </td> - <td> Custom fields of the product. </td> - </tr> - <tr> - <td colspan="2" class="no-top-border"> - <div class="field-arguments"> - <p class="field-arguments-header"> Arguments </p> - <div class="field-argument"> - <p class="field-argument-name"><code>names</code> - - <a href="#definition-String"><code>[String!]</code></a> default = <code>[]</code></p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>before</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>after</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>first</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>last</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - </div> - </td> - </tr> - <tr> - <td data-property-name="images"> <code>images</code> - - <a href="#definition-ImageConnection"><code>ImageConnection!</code></a> - </td> - <td> A list of the images for a product. </td> - </tr> - <tr> - <td colspan="2" class="no-top-border"> - <div class="field-arguments"> - <p class="field-arguments-header"> Arguments </p> - <div class="field-argument"> - <p class="field-argument-name"><code>before</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>after</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>first</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>last</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - </div> - </td> - </tr> - <tr> - <td data-property-name="defaultImage"> <code>defaultImage</code> - - <a href="#definition-Image"><code>Image</code></a> - </td> - <td> Default image for a product. </td> - </tr> - <tr> - <td data-property-name="relatedProducts"> <code>relatedProducts</code> - - <a href="#definition-RelatedProductsConnection"><code>RelatedProductsConnection!</code></a> - </td> - <td> Related products for this product. </td> - </tr> - <tr> - <td colspan="2" class="no-top-border"> - <div class="field-arguments"> - <p class="field-arguments-header"> Arguments </p> - <div class="field-argument"> - <p class="field-argument-name"><code>before</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>after</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>first</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>last</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - </div> - </td> - </tr> - <tr> - <td data-property-name="inventory"> <code>inventory</code> - - <a href="#definition-ProductInventory"><code>ProductInventory!</code></a> - </td> - <td> Inventory information of the product. </td> - </tr> - <tr> - <td data-property-name="metafields"> <code>metafields</code> - - <a href="#definition-MetafieldConnection"><code>MetafieldConnection!</code></a> - </td> - <td> Metafield data related to a product. </td> - </tr> - <tr> - <td colspan="2" class="no-top-border"> - <div class="field-arguments"> - <p class="field-arguments-header"> Arguments </p> - <div class="field-argument"> - <p class="field-argument-name"><code>namespace</code> - - <a href="#definition-String"><code>String!</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>keys</code> - - <a href="#definition-String"><code>[String!]</code></a> default = <code>[]</code></p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>before</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>after</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>first</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>last</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - </div> - </td> - </tr> - <tr> - <td data-property-name="upc"> <code>upc</code> - - <a href="#definition-String"><code>String</code></a> - </td> - <td> Universal product code. </td> - </tr> - <tr> - <td data-property-name="mpn"> <code>mpn</code> - - <a href="#definition-String"><code>String</code></a> - </td> - <td> Manufacturer part number. </td> - </tr> - <tr> - <td data-property-name="gtin"> <code>gtin</code> - - <a href="#definition-String"><code>String</code></a> - </td> - <td> Global trade item number. </td> - </tr> - <tr> - <td data-property-name="createdAt" class="swagger-operation-deprecated"> <code>createdAt</code> - - <a href="#definition-DateTimeExtended"><code>DateTimeExtended!</code></a> - </td> - <td> Product creation date - <span class="properties-deprecation-reason">Alpha version. Do not use in production.</span> - </td> - </tr> - <tr> - <td data-property-name="reviews"> <code>reviews</code> - - <a href="#definition-ReviewConnection"><code>ReviewConnection!</code></a> - </td> - <td> Reviews associated with the product. </td> - </tr> - <tr> - <td colspan="2" class="no-top-border"> - <div class="field-arguments"> - <p class="field-arguments-header"> Arguments </p> - <div class="field-argument"> - <p class="field-argument-name"><code>sort</code> - - <a href="#definition-ProductReviewsSortInput"><code>ProductReviewsSortInput</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>before</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>after</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>first</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>last</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - </div> - </td> - </tr> - <tr> - <td data-property-name="seo"> <code>seo</code> - - <a href="#definition-SeoDetails"><code>SeoDetails!</code></a> - </td> - <td> Product SEO details. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"id"</span>: ID, - <span class="hljs-attr">"entityId"</span>: <span class="hljs-number">123</span>, - <span class="hljs-attr">"sku"</span>: <span class="hljs-string">"abc123"</span>, - <span class="hljs-attr">"path"</span>: <span class="hljs-string">"abc123"</span>, - <span class="hljs-attr">"name"</span>: <span class="hljs-string">"xyz789"</span>, - <span class="hljs-attr">"description"</span>: <span class="hljs-string">"xyz789"</span>, - <span class="hljs-attr">"plainTextDescription"</span>: <span class="hljs-string">"abc123"</span>, - <span class="hljs-attr">"warranty"</span>: <span class="hljs-string">"xyz789"</span>, - <span class="hljs-attr">"minPurchaseQuantity"</span>: <span class="hljs-number">987</span>, - <span class="hljs-attr">"maxPurchaseQuantity"</span>: <span class="hljs-number">123</span>, - <span class="hljs-attr">"addToCartUrl"</span>: <span class="hljs-string">"abc123"</span>, - <span class="hljs-attr">"addToWishlistUrl"</span>: <span class="hljs-string">"xyz789"</span>, - <span class="hljs-attr">"prices"</span>: Prices, - <span class="hljs-attr">"priceRanges"</span>: PriceRanges, - <span class="hljs-attr">"weight"</span>: Measurement, - <span class="hljs-attr">"height"</span>: Measurement, - <span class="hljs-attr">"width"</span>: Measurement, - <span class="hljs-attr">"depth"</span>: Measurement, - <span class="hljs-attr">"options"</span>: OptionConnection, - <span class="hljs-attr">"productOptions"</span>: ProductOptionConnection, - <span class="hljs-attr">"reviewSummary"</span>: Reviews, - <span class="hljs-attr">"type"</span>: <span class="hljs-string">"abc123"</span>, - <span class="hljs-attr">"availability"</span>: <span class="hljs-string">"xyz789"</span>, - <span class="hljs-attr">"availabilityDescription"</span>: <span class="hljs-string">"abc123"</span>, - <span class="hljs-attr">"categories"</span>: CategoryConnection, - <span class="hljs-attr">"brand"</span>: Brand, - <span class="hljs-attr">"variants"</span>: VariantConnection, - <span class="hljs-attr">"customFields"</span>: CustomFieldConnection, - <span class="hljs-attr">"images"</span>: ImageConnection, - <span class="hljs-attr">"defaultImage"</span>: Image, - <span class="hljs-attr">"relatedProducts"</span>: RelatedProductsConnection, - <span class="hljs-attr">"inventory"</span>: ProductInventory, - <span class="hljs-attr">"metafields"</span>: MetafieldConnection, - <span class="hljs-attr">"upc"</span>: <span class="hljs-string">"abc123"</span>, - <span class="hljs-attr">"mpn"</span>: <span class="hljs-string">"abc123"</span>, - <span class="hljs-attr">"gtin"</span>: <span class="hljs-string">"xyz789"</span>, - <span class="hljs-attr">"createdAt"</span>: DateTimeExtended, - <span class="hljs-attr">"reviews"</span>: ReviewConnection, - <span class="hljs-attr">"seo"</span>: SeoDetails -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-ProductAttributeSearchFilterInput" class="definition panel" data-traverse-target="definition-ProductAttributeSearchFilterInput"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/ProductAttributeSearchFilterInput"></a> - <p><code>ProductAttributeSearchFilterInput</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Input Field</th> - <th>Description</th> - </tr> - <tr> - <td><code>attribute</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> </td> - </tr> - <tr> - <td><code>values</code> - - <a href="#definition-String"><code>[String!]!</code></a> - </td> - <td> </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"attribute"</span>: <span class="hljs-string">"abc123"</span>, <span class="hljs-attr">"values"</span>: [<span class="hljs-string">"xyz789"</span>]} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-ProductAvailabilityStatus" class="definition panel" data-traverse-target="definition-ProductAvailabilityStatus"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/ProductAvailabilityStatus"></a> - <p><code>ProductAvailabilityStatus</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Product availability status</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Enum Value</th> - <th>Description</th> - </tr> - <tr> - <td> - <p><code>Available</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>Preorder</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>Unavailable</code></p> - </td> - <td> </td> - </tr> - </table> - </section> - </div> - </div> - </div> - <div id="definition-ProductAvailable" class="definition panel" data-traverse-target="definition-ProductAvailable"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/ProductAvailable"></a> - <p><code>ProductAvailable</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Available Product</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="status"> <code>status</code> - - <a href="#definition-ProductAvailabilityStatus"><code>ProductAvailabilityStatus!</code></a> - </td> - <td> The availability state of the product. </td> - </tr> - <tr> - <td data-property-name="description"> <code>description</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> A few words telling the customer how long it will normally take to ship this product, such as 'Usually ships in 24 hours'. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"status"</span>: ProductAvailabilityStatus, - <span class="hljs-attr">"description"</span>: <span class="hljs-string">"abc123"</span> -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-ProductConnection" class="definition panel" data-traverse-target="definition-ProductConnection"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/ProductConnection"></a> - <p><code>ProductConnection</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>A connection to a list of items.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="pageInfo"> <code>pageInfo</code> - - <a href="#definition-PageInfo"><code>PageInfo!</code></a> - </td> - <td> Information to aid in pagination. </td> - </tr> - <tr> - <td data-property-name="edges"> <code>edges</code> - - <a href="#definition-ProductEdge"><code>[ProductEdge]</code></a> - </td> - <td> A list of edges. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"pageInfo"</span>: PageInfo, - <span class="hljs-attr">"edges"</span>: [ProductEdge] -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-ProductEdge" class="definition panel" data-traverse-target="definition-ProductEdge"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/ProductEdge"></a> - <p><code>ProductEdge</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>An edge in a connection.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="node"> <code>node</code> - - <a href="#definition-Product"><code>Product!</code></a> - </td> - <td> The item at the end of the edge. </td> - </tr> - <tr> - <td data-property-name="cursor"> <code>cursor</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> A cursor for use in pagination. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"node"</span>: Product, <span class="hljs-attr">"cursor"</span>: <span class="hljs-string">"abc123"</span>} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-ProductInventory" class="definition panel" data-traverse-target="definition-ProductInventory"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/ProductInventory"></a> - <p><code>ProductInventory</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Product Inventory Information</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="isInStock"> <code>isInStock</code> - - <a href="#definition-Boolean"><code>Boolean!</code></a> - </td> - <td> Indicates whether this product is in stock. </td> - </tr> - <tr> - <td data-property-name="hasVariantInventory"> <code>hasVariantInventory</code> - - <a href="#definition-Boolean"><code>Boolean!</code></a> - </td> - <td> Indicates whether this product's inventory is being tracked on variant level. If true, you may wish to check the variants node to understand the true inventory of each individual variant, rather than relying on this product-level aggregate to understand how many items may be added to cart. </td> - </tr> - <tr> - <td data-property-name="aggregated"> <code>aggregated</code> - - <a href="#definition-AggregatedInventory"><code>AggregatedInventory</code></a> - </td> - <td> Aggregated product inventory information. This data may not be available if not set or if the store's Inventory Settings have disabled displaying stock levels on the storefront. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"isInStock"</span>: <span class="hljs-literal">true</span>, - <span class="hljs-attr">"hasVariantInventory"</span>: <span class="hljs-literal">true</span>, - <span class="hljs-attr">"aggregated"</span>: AggregatedInventory -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-ProductOption" class="definition panel" data-traverse-target="definition-ProductOption"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/ProductOption"></a> - <p><code>ProductOption</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Product Option</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="entityId"> <code>entityId</code> - - <a href="#definition-Int"><code>Int!</code></a> - </td> - <td> Unique ID for the option. </td> - </tr> - <tr> - <td data-property-name="displayName"> <code>displayName</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Display name for the option. </td> - </tr> - <tr> - <td data-property-name="isRequired"> <code>isRequired</code> - - <a href="#definition-Boolean"><code>Boolean!</code></a> - </td> - <td> One of the option values is required to be selected for the checkout. </td> - </tr> - <tr> - <td data-property-name="values"> <code>values</code> - - <a href="#definition-OptionValueConnection"><code>OptionValueConnection!</code></a> - </td> - <td> Option values. </td> - </tr> - <tr> - <td colspan="2" class="no-top-border"> - <div class="field-arguments"> - <p class="field-arguments-header"> Arguments </p> - <div class="field-argument"> - <p class="field-argument-name"><code>before</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>after</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>first</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>last</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - </div> - </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"entityId"</span>: <span class="hljs-number">987</span>, - <span class="hljs-attr">"displayName"</span>: <span class="hljs-string">"xyz789"</span>, - <span class="hljs-attr">"isRequired"</span>: <span class="hljs-literal">false</span>, - <span class="hljs-attr">"values"</span>: OptionValueConnection -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-ProductOptionConnection" class="definition panel" data-traverse-target="definition-ProductOptionConnection"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/ProductOptionConnection"></a> - <p><code>ProductOptionConnection</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>A connection to a list of items.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="pageInfo"> <code>pageInfo</code> - - <a href="#definition-PageInfo"><code>PageInfo!</code></a> - </td> - <td> Information to aid in pagination. </td> - </tr> - <tr> - <td data-property-name="edges"> <code>edges</code> - - <a href="#definition-ProductOptionEdge"><code>[ProductOptionEdge]</code></a> - </td> - <td> A list of edges. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"pageInfo"</span>: PageInfo, - <span class="hljs-attr">"edges"</span>: [ProductOptionEdge] -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-ProductOptionEdge" class="definition panel" data-traverse-target="definition-ProductOptionEdge"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/ProductOptionEdge"></a> - <p><code>ProductOptionEdge</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>An edge in a connection.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="cursor"> <code>cursor</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> A cursor for use in pagination. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"cursor"</span>: <span class="hljs-string">"abc123"</span>} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-ProductOptionValue" class="definition panel" data-traverse-target="definition-ProductOptionValue"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/ProductOptionValue"></a> - <p><code>ProductOptionValue</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Product Option Value</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="entityId"> <code>entityId</code> - - <a href="#definition-Int"><code>Int!</code></a> - </td> - <td> Unique ID for the option value. </td> - </tr> - <tr> - <td data-property-name="label"> <code>label</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Label for the option value. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"entityId"</span>: <span class="hljs-number">123</span>, <span class="hljs-attr">"label"</span>: <span class="hljs-string">"abc123"</span>} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-ProductOptionValueConnection" class="definition panel" data-traverse-target="definition-ProductOptionValueConnection"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/ProductOptionValueConnection"></a> - <p><code>ProductOptionValueConnection</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>A connection to a list of items.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="pageInfo"> <code>pageInfo</code> - - <a href="#definition-PageInfo"><code>PageInfo!</code></a> - </td> - <td> Information to aid in pagination. </td> - </tr> - <tr> - <td data-property-name="edges"> <code>edges</code> - - <a href="#definition-ProductOptionValueEdge"><code>[ProductOptionValueEdge]</code></a> - </td> - <td> A list of edges. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"pageInfo"</span>: PageInfo, - <span class="hljs-attr">"edges"</span>: [ProductOptionValueEdge] -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-ProductOptionValueEdge" class="definition panel" data-traverse-target="definition-ProductOptionValueEdge"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/ProductOptionValueEdge"></a> - <p><code>ProductOptionValueEdge</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>An edge in a connection.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="cursor"> <code>cursor</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> A cursor for use in pagination. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"cursor"</span>: <span class="hljs-string">"xyz789"</span>} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-ProductPickListOptionValue" class="definition panel" data-traverse-target="definition-ProductPickListOptionValue"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/ProductPickListOptionValue"></a> - <p><code>ProductPickListOptionValue</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>A Product PickList Value - a product to be mapped to the base product if selected.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="productId"> <code>productId</code> - - <a href="#definition-Int"><code>Int!</code></a> - </td> - <td> The ID of the product associated with this option value. </td> - </tr> - <tr> - <td data-property-name="entityId"> <code>entityId</code> - - <a href="#definition-Int"><code>Int!</code></a> - </td> - <td> Unique ID for the option value. </td> - </tr> - <tr> - <td data-property-name="label"> <code>label</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Label for the option value. </td> - </tr> - <tr> - <td data-property-name="isDefault"> <code>isDefault</code> - - <a href="#definition-Boolean"><code>Boolean!</code></a> - </td> - <td> Indicates whether this value is the chosen default selected value. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"productId"</span>: <span class="hljs-number">123</span>, <span class="hljs-attr">"entityId"</span>: <span class="hljs-number">123</span>, <span class="hljs-attr">"label"</span>: <span class="hljs-string">"abc123"</span>, <span class="hljs-attr">"isDefault"</span>: <span class="hljs-literal">false</span>} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-ProductPreOrder" class="definition panel" data-traverse-target="definition-ProductPreOrder"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/ProductPreOrder"></a> - <p><code>ProductPreOrder</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>PreOrder Product</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="message"> <code>message</code> - - <a href="#definition-String"><code>String</code></a> - </td> - <td> The message to be shown in the store when a product is put into the pre-order availability state, e.g. "Expected release date is %%DATE%%" </td> - </tr> - <tr> - <td data-property-name="willBeReleasedAt"> <code>willBeReleasedAt</code> - - <a href="#definition-DateTimeExtended"><code>DateTimeExtended</code></a> - </td> - <td> Product release date </td> - </tr> - <tr> - <td data-property-name="status"> <code>status</code> - - <a href="#definition-ProductAvailabilityStatus"><code>ProductAvailabilityStatus!</code></a> - </td> - <td> The availability state of the product. </td> - </tr> - <tr> - <td data-property-name="description"> <code>description</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> A few words telling the customer how long it will normally take to ship this product, such as 'Usually ships in 24 hours'. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"message"</span>: <span class="hljs-string">"xyz789"</span>, - <span class="hljs-attr">"willBeReleasedAt"</span>: DateTimeExtended, - <span class="hljs-attr">"status"</span>: ProductAvailabilityStatus, - <span class="hljs-attr">"description"</span>: <span class="hljs-string">"xyz789"</span> -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-ProductReviewsSortInput" class="definition panel" data-traverse-target="definition-ProductReviewsSortInput"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/ProductReviewsSortInput"></a> - <p><code>ProductReviewsSortInput</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Enum Value</th> - <th>Description</th> - </tr> - <tr> - <td> - <p><code>NEWEST</code></p> - </td> - <td> </td> - </tr> - </table> - </section> - </div> - </div> - </div> - <div id="definition-ProductUnavailable" class="definition panel" data-traverse-target="definition-ProductUnavailable"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/ProductUnavailable"></a> - <p><code>ProductUnavailable</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Unavailable Product</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="message"> <code>message</code> - - <a href="#definition-String"><code>String</code></a> - </td> - <td> The message to be shown in the store when "Call for pricing" is enabled for this product, e.g. "Contact us at 555-5555" </td> - </tr> - <tr> - <td data-property-name="status"> <code>status</code> - - <a href="#definition-ProductAvailabilityStatus"><code>ProductAvailabilityStatus!</code></a> - </td> - <td> The availability state of the product. </td> - </tr> - <tr> - <td data-property-name="description"> <code>description</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> A few words telling the customer how long it will normally take to ship this product, such as 'Usually ships in 24 hours'. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"message"</span>: <span class="hljs-string">"xyz789"</span>, - <span class="hljs-attr">"status"</span>: ProductAvailabilityStatus, - <span class="hljs-attr">"description"</span>: <span class="hljs-string">"abc123"</span> -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-RatingSearchFilterInput" class="definition panel" data-traverse-target="definition-RatingSearchFilterInput"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/RatingSearchFilterInput"></a> - <p><code>RatingSearchFilterInput</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Input Field</th> - <th>Description</th> - </tr> - <tr> - <td><code>minRating</code> - - <a href="#definition-Float"><code>Float</code></a> - </td> - <td> </td> - </tr> - <tr> - <td><code>maxRating</code> - - <a href="#definition-Float"><code>Float</code></a> - </td> - <td> </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"minRating"</span>: <span class="hljs-number">123.45</span>, <span class="hljs-attr">"maxRating"</span>: <span class="hljs-number">123.45</span>} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-Region" class="definition panel" data-traverse-target="definition-Region"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/Region"></a> - <p><code>Region</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="name"> <code>name</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> The name of a region. </td> - </tr> - <tr> - <td data-property-name="html"> <code>html</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> The rendered HTML content targeted at the region. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"name"</span>: <span class="hljs-string">"abc123"</span>, <span class="hljs-attr">"html"</span>: <span class="hljs-string">"xyz789"</span>} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-RelatedProductsConnection" class="definition panel" data-traverse-target="definition-RelatedProductsConnection"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/RelatedProductsConnection"></a> - <p><code>RelatedProductsConnection</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>A connection to a list of items.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="pageInfo"> <code>pageInfo</code> - - <a href="#definition-PageInfo"><code>PageInfo!</code></a> - </td> - <td> Information to aid in pagination. </td> - </tr> - <tr> - <td data-property-name="edges"> <code>edges</code> - - <a href="#definition-RelatedProductsEdge"><code>[RelatedProductsEdge]</code></a> - </td> - <td> A list of edges. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"pageInfo"</span>: PageInfo, - <span class="hljs-attr">"edges"</span>: [RelatedProductsEdge] -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-RelatedProductsEdge" class="definition panel" data-traverse-target="definition-RelatedProductsEdge"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/RelatedProductsEdge"></a> - <p><code>RelatedProductsEdge</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>An edge in a connection.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="node"> <code>node</code> - - <a href="#definition-Product"><code>Product!</code></a> - </td> - <td> The item at the end of the edge. </td> - </tr> - <tr> - <td data-property-name="cursor"> <code>cursor</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> A cursor for use in pagination. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"node"</span>: Product, <span class="hljs-attr">"cursor"</span>: <span class="hljs-string">"abc123"</span>} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-RenderedRegionsByPageType" class="definition panel" data-traverse-target="definition-RenderedRegionsByPageType"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/RenderedRegionsByPageType"></a> - <p><code>RenderedRegionsByPageType</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>The rendered regions by specific page.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="regions"> <code>regions</code> - - <a href="#definition-Region"><code>[Region!]!</code></a> - </td> - <td> </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"regions"</span>: [Region]} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-Review" class="definition panel" data-traverse-target="definition-Review"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/Review"></a> - <p><code>Review</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Review</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="entityId"> <code>entityId</code> - - <a href="#definition-Long"><code>Long!</code></a> - </td> - <td> Unique ID for the product review. </td> - </tr> - <tr> - <td data-property-name="author"> <code>author</code> - - <a href="#definition-Author"><code>Author!</code></a> - </td> - <td> Product review author. </td> - </tr> - <tr> - <td data-property-name="title"> <code>title</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Product review title. </td> - </tr> - <tr> - <td data-property-name="text"> <code>text</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Product review text. </td> - </tr> - <tr> - <td data-property-name="rating"> <code>rating</code> - - <a href="#definition-Int"><code>Int!</code></a> - </td> - <td> Product review rating. </td> - </tr> - <tr> - <td data-property-name="createdAt"> <code>createdAt</code> - - <a href="#definition-DateTimeExtended"><code>DateTimeExtended!</code></a> - </td> - <td> Product review creation date. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"entityId"</span>: Long, - <span class="hljs-attr">"author"</span>: Author, - <span class="hljs-attr">"title"</span>: <span class="hljs-string">"abc123"</span>, - <span class="hljs-attr">"text"</span>: <span class="hljs-string">"abc123"</span>, - <span class="hljs-attr">"rating"</span>: <span class="hljs-number">987</span>, - <span class="hljs-attr">"createdAt"</span>: DateTimeExtended -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-ReviewConnection" class="definition panel" data-traverse-target="definition-ReviewConnection"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/ReviewConnection"></a> - <p><code>ReviewConnection</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>A connection to a list of items.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="pageInfo"> <code>pageInfo</code> - - <a href="#definition-PageInfo"><code>PageInfo!</code></a> - </td> - <td> Information to aid in pagination. </td> - </tr> - <tr> - <td data-property-name="edges"> <code>edges</code> - - <a href="#definition-ReviewEdge"><code>[ReviewEdge]</code></a> - </td> - <td> A list of edges. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"pageInfo"</span>: PageInfo, - <span class="hljs-attr">"edges"</span>: [ReviewEdge] -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-ReviewEdge" class="definition panel" data-traverse-target="definition-ReviewEdge"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/ReviewEdge"></a> - <p><code>ReviewEdge</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>An edge in a connection.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="node"> <code>node</code> - - <a href="#definition-Review"><code>Review!</code></a> - </td> - <td> The item at the end of the edge. </td> - </tr> - <tr> - <td data-property-name="cursor"> <code>cursor</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> A cursor for use in pagination. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"node"</span>: Review, <span class="hljs-attr">"cursor"</span>: <span class="hljs-string">"xyz789"</span>} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-Reviews" class="definition panel" data-traverse-target="definition-Reviews"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/Reviews"></a> - <p><code>Reviews</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Review Rating Summary</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="averageRating" class="swagger-operation-deprecated"> <code>averageRating</code> - - <a href="#definition-Float"><code>Float!</code></a> - </td> - <td> Average rating of the product. - <span class="properties-deprecation-reason">Alpha version. Do not use in production.</span> - </td> - </tr> - <tr> - <td data-property-name="numberOfReviews"> <code>numberOfReviews</code> - - <a href="#definition-Int"><code>Int!</code></a> - </td> - <td> Total number of reviews on product. </td> - </tr> - <tr> - <td data-property-name="summationOfRatings"> <code>summationOfRatings</code> - - <a href="#definition-Int"><code>Int!</code></a> - </td> - <td> Summation of rating scores from each review. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"averageRating"</span>: <span class="hljs-number">987.65</span>, <span class="hljs-attr">"numberOfReviews"</span>: <span class="hljs-number">123</span>, <span class="hljs-attr">"summationOfRatings"</span>: <span class="hljs-number">987</span>} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-Route" class="definition panel" data-traverse-target="definition-Route"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/Route"></a> - <p><code>Route</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>route</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-Search" class="definition panel" data-traverse-target="definition-Search"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/Search"></a> - <p><code>Search</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Store search settings.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="productFilteringEnabled"> <code>productFilteringEnabled</code> - - <a href="#definition-Boolean"><code>Boolean!</code></a> - </td> - <td> Product filtering enabled. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"productFilteringEnabled"</span>: <span class="hljs-literal">true</span>} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-SearchProducts" class="definition panel" data-traverse-target="definition-SearchProducts"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/SearchProducts"></a> - <p><code>SearchProducts</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="products"> <code>products</code> - - <a href="#definition-ProductConnection"><code>ProductConnection!</code></a> - </td> - <td> Details of the products. </td> - </tr> - <tr> - <td colspan="2" class="no-top-border"> - <div class="field-arguments"> - <p class="field-arguments-header"> Arguments </p> - <div class="field-argument"> - <p class="field-argument-name"><code>after</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>first</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - </div> - </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"products"</span>: ProductConnection} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-SearchProductsFiltersInput" class="definition panel" data-traverse-target="definition-SearchProductsFiltersInput"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/SearchProductsFiltersInput"></a> - <p><code>SearchProductsFiltersInput</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Input Field</th> - <th>Description</th> - </tr> - <tr> - <td><code>searchTerm</code> - - <a href="#definition-String"><code>String</code></a> - </td> - <td> </td> - </tr> - <tr> - <td><code>price</code> - - <a href="#definition-PriceSearchFilterInput"><code>PriceSearchFilterInput</code></a> - </td> - <td> </td> - </tr> - <tr> - <td><code>rating</code> - - <a href="#definition-RatingSearchFilterInput"><code>RatingSearchFilterInput</code></a> - </td> - <td> </td> - </tr> - <tr> - <td><code>categoryEntityId</code> - - <a href="#definition-Int"><code>Int</code></a> - </td> - <td> </td> - </tr> - <tr> - <td><code>categoryEntityIds</code> - - <a href="#definition-Int"><code>[Int!]</code></a> - </td> - <td> </td> - </tr> - <tr> - <td><code>brandEntityIds</code> - - <a href="#definition-Int"><code>[Int!]</code></a> - </td> - <td> </td> - </tr> - <tr> - <td><code>productAttributes</code> - - <a href="#definition-ProductAttributeSearchFilterInput"><code>[ProductAttributeSearchFilterInput!]</code></a> - </td> - <td> </td> - </tr> - <tr> - <td><code>isFreeShipping</code> - - <a href="#definition-Boolean"><code>Boolean</code></a> - </td> - <td> </td> - </tr> - <tr> - <td><code>isFeatured</code> - - <a href="#definition-Boolean"><code>Boolean</code></a> - </td> - <td> </td> - </tr> - <tr> - <td><code>isInStock</code> - - <a href="#definition-Boolean"><code>Boolean</code></a> - </td> - <td> </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"searchTerm"</span>: <span class="hljs-string">"abc123"</span>, - <span class="hljs-attr">"price"</span>: PriceSearchFilterInput, - <span class="hljs-attr">"rating"</span>: RatingSearchFilterInput, - <span class="hljs-attr">"categoryEntityId"</span>: <span class="hljs-number">123</span>, - <span class="hljs-attr">"categoryEntityIds"</span>: [<span class="hljs-number">987</span>], - <span class="hljs-attr">"brandEntityIds"</span>: [<span class="hljs-number">987</span>], - <span class="hljs-attr">"productAttributes"</span>: [ - ProductAttributeSearchFilterInput - ], - <span class="hljs-attr">"isFreeShipping"</span>: <span class="hljs-literal">true</span>, - <span class="hljs-attr">"isFeatured"</span>: <span class="hljs-literal">true</span>, - <span class="hljs-attr">"isInStock"</span>: <span class="hljs-literal">false</span> -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-SearchProductsSortInput" class="definition panel" data-traverse-target="definition-SearchProductsSortInput"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/SearchProductsSortInput"></a> - <p><code>SearchProductsSortInput</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Enum Value</th> - <th>Description</th> - </tr> - <tr> - <td> - <p><code>FEATURED</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>NEWEST</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BEST_SELLING</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BEST_REVIEWED</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>A_TO_Z</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>Z_TO_A</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>LOWEST_PRICE</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>HIGHEST_PRICE</code></p> - </td> - <td> </td> - </tr> - </table> - </section> - </div> - </div> - </div> - <div id="definition-SearchQueries" class="definition panel" data-traverse-target="definition-SearchQueries"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/SearchQueries"></a> - <p><code>SearchQueries</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="searchProducts"> <code>searchProducts</code> - - <a href="#definition-SearchProducts"><code>SearchProducts!</code></a> - </td> - <td> Details of the products and facets matching given search criteria. </td> - </tr> - <tr> - <td colspan="2" class="no-top-border"> - <div class="field-arguments"> - <p class="field-arguments-header"> Arguments </p> - <div class="field-argument"> - <p class="field-argument-name"><code>filters</code> - - <a href="#definition-SearchProductsFiltersInput"><code>SearchProductsFiltersInput!</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>sort</code> - - <a href="#definition-SearchProductsSortInput"><code>SearchProductsSortInput</code></a> - </p> - </div> - </div> - </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"searchProducts"</span>: SearchProducts} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-SeoDetails" class="definition panel" data-traverse-target="definition-SeoDetails"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/SeoDetails"></a> - <p><code>SeoDetails</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Seo Details</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="pageTitle"> <code>pageTitle</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Page title. </td> - </tr> - <tr> - <td data-property-name="metaDescription"> <code>metaDescription</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Meta description. </td> - </tr> - <tr> - <td data-property-name="metaKeywords"> <code>metaKeywords</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Meta keywords. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"pageTitle"</span>: <span class="hljs-string">"xyz789"</span>, <span class="hljs-attr">"metaDescription"</span>: <span class="hljs-string">"abc123"</span>, <span class="hljs-attr">"metaKeywords"</span>: <span class="hljs-string">"abc123"</span>} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-Settings" class="definition panel" data-traverse-target="definition-Settings"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/Settings"></a> - <p><code>Settings</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Store settings information from the control panel.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="storeName"> <code>storeName</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> The name of the store. </td> - </tr> - <tr> - <td data-property-name="storeHash"> <code>storeHash</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> The hash of the store. </td> - </tr> - <tr> - <td data-property-name="status"> <code>status</code> - - <a href="#definition-StorefrontStatusType"><code>StorefrontStatusType!</code></a> - </td> - <td> The current store status. </td> - </tr> - <tr> - <td data-property-name="logo"> <code>logo</code> - - <a href="#definition-LogoField"><code>LogoField!</code></a> - </td> - <td> Logo information for the store. </td> - </tr> - <tr> - <td data-property-name="contact"> <code>contact</code> - - <a href="#definition-ContactField"><code>ContactField</code></a> - </td> - <td> Contact information for the store. </td> - </tr> - <tr> - <td data-property-name="url"> <code>url</code> - - <a href="#definition-UrlField"><code>UrlField!</code></a> - </td> - <td> Store urls. </td> - </tr> - <tr> - <td data-property-name="display"> <code>display</code> - - <a href="#definition-DisplayField"><code>DisplayField!</code></a> - </td> - <td> Store display format information. </td> - </tr> - <tr> - <td data-property-name="channelId"> <code>channelId</code> - - <a href="#definition-Long"><code>Long!</code></a> - </td> - <td> Channel ID. </td> - </tr> - <tr> - <td data-property-name="tax"> <code>tax</code> - - <a href="#definition-TaxDisplaySettings"><code>TaxDisplaySettings</code></a> - </td> - <td> </td> - </tr> - <tr> - <td data-property-name="search"> <code>search</code> - - <a href="#definition-Search"><code>Search!</code></a> - </td> - <td> Store search settings. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"storeName"</span>: <span class="hljs-string">"abc123"</span>, - <span class="hljs-attr">"storeHash"</span>: <span class="hljs-string">"xyz789"</span>, - <span class="hljs-attr">"status"</span>: StorefrontStatusType, - <span class="hljs-attr">"logo"</span>: LogoField, - <span class="hljs-attr">"contact"</span>: ContactField, - <span class="hljs-attr">"url"</span>: UrlField, - <span class="hljs-attr">"display"</span>: DisplayField, - <span class="hljs-attr">"channelId"</span>: Long, - <span class="hljs-attr">"tax"</span>: TaxDisplaySettings, - <span class="hljs-attr">"search"</span>: Search -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-Site" class="definition panel" data-traverse-target="definition-Site"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/Site"></a> - <p><code>Site</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>A site</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="search" class="swagger-operation-deprecated"> <code>search</code> - - <a href="#definition-SearchQueries"><code>SearchQueries!</code></a> - </td> - <td> The Search queries. - <span class="properties-deprecation-reason">Alpha version. Do not use in production.</span> - </td> - </tr> - <tr> - <td data-property-name="categoryTree"> <code>categoryTree</code> - - <a href="#definition-CategoryTreeItem"><code>[CategoryTreeItem!]!</code></a> - </td> - <td> </td> - </tr> - <tr> - <td colspan="2" class="no-top-border"> - <div class="field-arguments"> - <p class="field-arguments-header"> Arguments </p> - <div class="field-argument"> - <p class="field-argument-name"><code>rootEntityId</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - </div> - </td> - </tr> - <tr> - <td data-property-name="brands"> <code>brands</code> - - <a href="#definition-BrandConnection"><code>BrandConnection!</code></a> - </td> - <td> Details of the brand. </td> - </tr> - <tr> - <td colspan="2" class="no-top-border"> - <div class="field-arguments"> - <p class="field-arguments-header"> Arguments </p> - <div class="field-argument"> - <p class="field-argument-name"><code>before</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>after</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>first</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>last</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>productEntityIds</code> - - <a href="#definition-Int"><code>[Int!]</code></a> default = <code>[]</code></p> - </div> - </div> - </td> - </tr> - <tr> - <td data-property-name="products"> <code>products</code> - - <a href="#definition-ProductConnection"><code>ProductConnection!</code></a> - </td> - <td> Details of the products. </td> - </tr> - <tr> - <td colspan="2" class="no-top-border"> - <div class="field-arguments"> - <p class="field-arguments-header"> Arguments </p> - <div class="field-argument"> - <p class="field-argument-name"><code>before</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>after</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>first</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>last</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>ids</code> - - <a href="#definition-ID"><code>[ID!]</code></a> default = <code>[]</code></p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>entityIds</code> - - <a href="#definition-Int"><code>[Int!]</code></a> default = <code>[]</code></p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>hideOutOfStock</code> - - <a href="#definition-Boolean"><code>Boolean</code></a> - </p> - </div> - </div> - </td> - </tr> - <tr> - <td data-property-name="newestProducts"> <code>newestProducts</code> - - <a href="#definition-ProductConnection"><code>ProductConnection!</code></a> - </td> - <td> Details of the newest products. </td> - </tr> - <tr> - <td colspan="2" class="no-top-border"> - <div class="field-arguments"> - <p class="field-arguments-header"> Arguments </p> - <div class="field-argument"> - <p class="field-argument-name"><code>before</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>after</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>first</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>last</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>hideOutOfStock</code> - - <a href="#definition-Boolean"><code>Boolean</code></a> - </p> - </div> - </div> - </td> - </tr> - <tr> - <td data-property-name="bestSellingProducts"> <code>bestSellingProducts</code> - - <a href="#definition-ProductConnection"><code>ProductConnection!</code></a> - </td> - <td> Details of the best selling products. </td> - </tr> - <tr> - <td colspan="2" class="no-top-border"> - <div class="field-arguments"> - <p class="field-arguments-header"> Arguments </p> - <div class="field-argument"> - <p class="field-argument-name"><code>before</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>after</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>first</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>last</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>hideOutOfStock</code> - - <a href="#definition-Boolean"><code>Boolean</code></a> - </p> - </div> - </div> - </td> - </tr> - <tr> - <td data-property-name="featuredProducts"> <code>featuredProducts</code> - - <a href="#definition-ProductConnection"><code>ProductConnection!</code></a> - </td> - <td> Details of the featured products. </td> - </tr> - <tr> - <td colspan="2" class="no-top-border"> - <div class="field-arguments"> - <p class="field-arguments-header"> Arguments </p> - <div class="field-argument"> - <p class="field-argument-name"><code>before</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>after</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>first</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>last</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>hideOutOfStock</code> - - <a href="#definition-Boolean"><code>Boolean</code></a> - </p> - </div> - </div> - </td> - </tr> - <tr> - <td data-property-name="product"> <code>product</code> - - <a href="#definition-Product"><code>Product</code></a> - </td> - <td> A single product object with variant pricing overlay capabilities. </td> - </tr> - <tr> - <td colspan="2" class="no-top-border"> - <div class="field-arguments"> - <p class="field-arguments-header"> Arguments </p> - <div class="field-argument"> - <p class="field-argument-name"><code>id</code> - - <a href="#definition-ID"><code>ID</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>entityId</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>variantEntityId</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>optionValueIds</code> - - <a href="#definition-OptionValueId"><code>[OptionValueId!]</code></a> default = <code>[]</code></p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>sku</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - </div> - </td> - </tr> - <tr> - <td data-property-name="route"> <code>route</code> - - <a href="#definition-Route"><code>Route!</code></a> - </td> - <td> Route for a node </td> - </tr> - <tr> - <td colspan="2" class="no-top-border"> - <div class="field-arguments"> - <p class="field-arguments-header"> Arguments </p> - <div class="field-argument"> - <p class="field-argument-name"><code>path</code> - - <a href="#definition-String"><code>String!</code></a> - </p> - </div> - </div> - </td> - </tr> - <tr> - <td data-property-name="settings"> <code>settings</code> - - <a href="#definition-Settings"><code>Settings</code></a> - </td> - <td> Store settings. </td> - </tr> - <tr> - <td data-property-name="content"> <code>content</code> - - <a href="#definition-Content"><code>Content!</code></a> - </td> - <td> </td> - </tr> - <tr> - <td data-property-name="currency"> <code>currency</code> - - <a href="#definition-Currency"><code>Currency</code></a> - </td> - <td> Currency details. </td> - </tr> - <tr> - <td colspan="2" class="no-top-border"> - <div class="field-arguments"> - <p class="field-arguments-header"> Arguments </p> - <div class="field-argument"> - <p class="field-argument-name"><code>currencyCode</code> - - <a href="#definition-currencyCode"><code>currencyCode!</code></a> - </p> - <p> - <p>Currency Code</p> - </p> - </div> - </div> - </td> - </tr> - <tr> - <td data-property-name="currencies"> <code>currencies</code> - - <a href="#definition-CurrencyConnection"><code>CurrencyConnection!</code></a> - </td> - <td> Store Currencies. </td> - </tr> - <tr> - <td colspan="2" class="no-top-border"> - <div class="field-arguments"> - <p class="field-arguments-header"> Arguments </p> - <div class="field-argument"> - <p class="field-argument-name"><code>before</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>after</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>first</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>last</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - </div> - </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"search"</span>: SearchQueries, - <span class="hljs-attr">"categoryTree"</span>: [CategoryTreeItem], - <span class="hljs-attr">"brands"</span>: BrandConnection, - <span class="hljs-attr">"products"</span>: ProductConnection, - <span class="hljs-attr">"newestProducts"</span>: ProductConnection, - <span class="hljs-attr">"bestSellingProducts"</span>: ProductConnection, - <span class="hljs-attr">"featuredProducts"</span>: ProductConnection, - <span class="hljs-attr">"product"</span>: Product, - <span class="hljs-attr">"route"</span>: Route, - <span class="hljs-attr">"settings"</span>: Settings, - <span class="hljs-attr">"content"</span>: Content, - <span class="hljs-attr">"currency"</span>: Currency, - <span class="hljs-attr">"currencies"</span>: CurrencyConnection -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-StorefrontStatusType" class="definition panel" data-traverse-target="definition-StorefrontStatusType"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/StorefrontStatusType"></a> - <p><code>StorefrontStatusType</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Storefront Mode</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Enum Value</th> - <th>Description</th> - </tr> - <tr> - <td> - <p><code>LAUNCHED</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MAINTENANCE</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>PRE_LAUNCH</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>HIBERNATION</code></p> - </td> - <td> </td> - </tr> - </table> - </section> - </div> - </div> - </div> - <div id="definition-String" class="definition panel" data-traverse-target="definition-String"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/String"></a> - <p><code>String</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>The <code>String</code> scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.</p> - </section> - </div> - </div> - </div> - <div id="definition-SwatchOptionValue" class="definition panel" data-traverse-target="definition-SwatchOptionValue"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/SwatchOptionValue"></a> - <p><code>SwatchOptionValue</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>A swatch option value - swatch values can be associated with a list of hexidecimal colors or an image.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="hexColors"> <code>hexColors</code> - - <a href="#definition-String"><code>[String!]!</code></a> - </td> - <td> List of up to 3 hex encoded colors to associate with a swatch value. </td> - </tr> - <tr> - <td data-property-name="imageUrl"> <code>imageUrl</code> - - <a href="#definition-String"><code>String</code></a> - </td> - <td> Absolute path of a swatch texture image. </td> - </tr> - <tr> - <td colspan="2" class="no-top-border"> - <div class="field-arguments"> - <p class="field-arguments-header"> Arguments </p> - <div class="field-argument"> - <p class="field-argument-name"><code>width</code> - - <a href="#definition-Int"><code>Int!</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>height</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - </div> - </td> - </tr> - <tr> - <td data-property-name="entityId"> <code>entityId</code> - - <a href="#definition-Int"><code>Int!</code></a> - </td> - <td> Unique ID for the option value. </td> - </tr> - <tr> - <td data-property-name="label"> <code>label</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Label for the option value. </td> - </tr> - <tr> - <td data-property-name="isDefault"> <code>isDefault</code> - - <a href="#definition-Boolean"><code>Boolean!</code></a> - </td> - <td> Indicates whether this value is the chosen default selected value. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"hexColors"</span>: [<span class="hljs-string">"xyz789"</span>], - <span class="hljs-attr">"imageUrl"</span>: <span class="hljs-string">"xyz789"</span>, - <span class="hljs-attr">"entityId"</span>: <span class="hljs-number">987</span>, - <span class="hljs-attr">"label"</span>: <span class="hljs-string">"abc123"</span>, - <span class="hljs-attr">"isDefault"</span>: <span class="hljs-literal">false</span> -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-TaxDisplaySettings" class="definition panel" data-traverse-target="definition-TaxDisplaySettings"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/TaxDisplaySettings"></a> - <p><code>TaxDisplaySettings</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="pdp"> <code>pdp</code> - - <a href="#definition-TaxPriceDisplay"><code>TaxPriceDisplay!</code></a> - </td> - <td> Tax display setting for Product Details Page. </td> - </tr> - <tr> - <td data-property-name="plp"> <code>plp</code> - - <a href="#definition-TaxPriceDisplay"><code>TaxPriceDisplay!</code></a> - </td> - <td> Tax display setting for Product List Page. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"pdp"</span>: TaxPriceDisplay, - <span class="hljs-attr">"plp"</span>: TaxPriceDisplay -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-TaxPriceDisplay" class="definition panel" data-traverse-target="definition-TaxPriceDisplay"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/TaxPriceDisplay"></a> - <p><code>TaxPriceDisplay</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Tax setting can be set included or excluded (Tax setting can also be set to both on PDP/PLP).</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Enum Value</th> - <th>Description</th> - </tr> - <tr> - <td> - <p><code>INC</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>EX</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BOTH</code></p> - </td> - <td> </td> - </tr> - </table> - </section> - </div> - </div> - </div> - <div id="definition-TextFieldOption" class="definition panel" data-traverse-target="definition-TextFieldOption"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/TextFieldOption"></a> - <p><code>TextFieldOption</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>A single line text input field.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="entityId"> <code>entityId</code> - - <a href="#definition-Int"><code>Int!</code></a> - </td> - <td> Unique ID for the option. </td> - </tr> - <tr> - <td data-property-name="displayName"> <code>displayName</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Display name for the option. </td> - </tr> - <tr> - <td data-property-name="isRequired"> <code>isRequired</code> - - <a href="#definition-Boolean"><code>Boolean!</code></a> - </td> - <td> One of the option values is required to be selected for the checkout. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"entityId"</span>: <span class="hljs-number">123</span>, <span class="hljs-attr">"displayName"</span>: <span class="hljs-string">"xyz789"</span>, <span class="hljs-attr">"isRequired"</span>: <span class="hljs-literal">false</span>} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-UrlField" class="definition panel" data-traverse-target="definition-UrlField"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/UrlField"></a> - <p><code>UrlField</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Url field</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="vanityUrl"> <code>vanityUrl</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Store url. </td> - </tr> - <tr> - <td data-property-name="cdnUrl"> <code>cdnUrl</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> CDN url to fetch assets. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"vanityUrl"</span>: <span class="hljs-string">"abc123"</span>, <span class="hljs-attr">"cdnUrl"</span>: <span class="hljs-string">"abc123"</span>} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-Variant" class="definition panel" data-traverse-target="definition-Variant"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/Variant"></a> - <p><code>Variant</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Variant</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="id"> <code>id</code> - - <a href="#definition-ID"><code>ID!</code></a> - </td> - <td> The ID of an object </td> - </tr> - <tr> - <td data-property-name="entityId"> <code>entityId</code> - - <a href="#definition-Int"><code>Int!</code></a> - </td> - <td> Id of the variant. </td> - </tr> - <tr> - <td data-property-name="sku"> <code>sku</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> Sku of the variant. </td> - </tr> - <tr> - <td data-property-name="weight"> <code>weight</code> - - <a href="#definition-Measurement"><code>Measurement</code></a> - </td> - <td> The variant's weight. If a weight was not explicitly specified on the variant, this will be the product's weight. </td> - </tr> - <tr> - <td data-property-name="height"> <code>height</code> - - <a href="#definition-Measurement"><code>Measurement</code></a> - </td> - <td> The variant's height. If a height was not explicitly specified on the variant, this will be the product's height. </td> - </tr> - <tr> - <td data-property-name="width"> <code>width</code> - - <a href="#definition-Measurement"><code>Measurement</code></a> - </td> - <td> The variant's width. If a width was not explicitly specified on the variant, this will be the product's width. </td> - </tr> - <tr> - <td data-property-name="depth"> <code>depth</code> - - <a href="#definition-Measurement"><code>Measurement</code></a> - </td> - <td> The variant's depth. If a depth was not explicitly specified on the variant, this will be the product's depth. </td> - </tr> - <tr> - <td data-property-name="options"> <code>options</code> - - <a href="#definition-OptionConnection"><code>OptionConnection!</code></a> - </td> - <td> The options which define a variant. </td> - </tr> - <tr> - <td colspan="2" class="no-top-border"> - <div class="field-arguments"> - <p class="field-arguments-header"> Arguments </p> - <div class="field-argument"> - <p class="field-argument-name"><code>before</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>after</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>first</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>last</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - </div> - </td> - </tr> - <tr> - <td data-property-name="productOptions"> <code>productOptions</code> - - <a href="#definition-ProductOptionConnection"><code>ProductOptionConnection!</code></a> - </td> - <td> Product options that compose this variant. </td> - </tr> - <tr> - <td colspan="2" class="no-top-border"> - <div class="field-arguments"> - <p class="field-arguments-header"> Arguments </p> - <div class="field-argument"> - <p class="field-argument-name"><code>before</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>after</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>first</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>last</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - </div> - </td> - </tr> - <tr> - <td data-property-name="defaultImage"> <code>defaultImage</code> - - <a href="#definition-Image"><code>Image</code></a> - </td> - <td> Default image for a variant. </td> - </tr> - <tr> - <td data-property-name="prices"> <code>prices</code> - - <a href="#definition-Prices"><code>Prices</code></a> - </td> - <td> Variant prices </td> - </tr> - <tr> - <td colspan="2" class="no-top-border"> - <div class="field-arguments"> - <p class="field-arguments-header"> Arguments </p> - <div class="field-argument"> - <p class="field-argument-name"><code>includeTax</code> - - <a href="#definition-Boolean"><code>Boolean</code></a> default = <code>false</code></p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>currencyCode</code> - - <a href="#definition-currencyCode"><code>currencyCode</code></a> - </p> - <p> - <p>Please select a currency</p> - </p> - </div> - </div> - </td> - </tr> - <tr> - <td data-property-name="inventory"> <code>inventory</code> - - <a href="#definition-VariantInventory"><code>VariantInventory</code></a> - </td> - <td> Variant inventory </td> - </tr> - <tr> - <td data-property-name="metafields"> <code>metafields</code> - - <a href="#definition-MetafieldConnection"><code>MetafieldConnection!</code></a> - </td> - <td> Metafield data related to a variant. </td> - </tr> - <tr> - <td colspan="2" class="no-top-border"> - <div class="field-arguments"> - <p class="field-arguments-header"> Arguments </p> - <div class="field-argument"> - <p class="field-argument-name"><code>namespace</code> - - <a href="#definition-String"><code>String!</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>keys</code> - - <a href="#definition-String"><code>[String!]</code></a> default = <code>[]</code></p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>before</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>after</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>first</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>last</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - </div> - </td> - </tr> - <tr> - <td data-property-name="upc"> <code>upc</code> - - <a href="#definition-String"><code>String</code></a> - </td> - <td> Universal product code. </td> - </tr> - <tr> - <td data-property-name="mpn"> <code>mpn</code> - - <a href="#definition-String"><code>String</code></a> - </td> - <td> Manufacturer part number. </td> - </tr> - <tr> - <td data-property-name="gtin"> <code>gtin</code> - - <a href="#definition-String"><code>String</code></a> - </td> - <td> Global trade item number. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"id"</span>: ID, - <span class="hljs-attr">"entityId"</span>: <span class="hljs-number">987</span>, - <span class="hljs-attr">"sku"</span>: <span class="hljs-string">"xyz789"</span>, - <span class="hljs-attr">"weight"</span>: Measurement, - <span class="hljs-attr">"height"</span>: Measurement, - <span class="hljs-attr">"width"</span>: Measurement, - <span class="hljs-attr">"depth"</span>: Measurement, - <span class="hljs-attr">"options"</span>: OptionConnection, - <span class="hljs-attr">"productOptions"</span>: ProductOptionConnection, - <span class="hljs-attr">"defaultImage"</span>: Image, - <span class="hljs-attr">"prices"</span>: Prices, - <span class="hljs-attr">"inventory"</span>: VariantInventory, - <span class="hljs-attr">"metafields"</span>: MetafieldConnection, - <span class="hljs-attr">"upc"</span>: <span class="hljs-string">"abc123"</span>, - <span class="hljs-attr">"mpn"</span>: <span class="hljs-string">"xyz789"</span>, - <span class="hljs-attr">"gtin"</span>: <span class="hljs-string">"xyz789"</span> -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-VariantConnection" class="definition panel" data-traverse-target="definition-VariantConnection"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/VariantConnection"></a> - <p><code>VariantConnection</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>A connection to a list of items.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="pageInfo"> <code>pageInfo</code> - - <a href="#definition-PageInfo"><code>PageInfo!</code></a> - </td> - <td> Information to aid in pagination. </td> - </tr> - <tr> - <td data-property-name="edges"> <code>edges</code> - - <a href="#definition-VariantEdge"><code>[VariantEdge]</code></a> - </td> - <td> A list of edges. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"pageInfo"</span>: PageInfo, - <span class="hljs-attr">"edges"</span>: [VariantEdge] -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-VariantEdge" class="definition panel" data-traverse-target="definition-VariantEdge"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/VariantEdge"></a> - <p><code>VariantEdge</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>An edge in a connection.</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="node"> <code>node</code> - - <a href="#definition-Variant"><code>Variant!</code></a> - </td> - <td> The item at the end of the edge. </td> - </tr> - <tr> - <td data-property-name="cursor"> <code>cursor</code> - - <a href="#definition-String"><code>String!</code></a> - </td> - <td> A cursor for use in pagination. </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{<span class="hljs-attr">"node"</span>: Variant, <span class="hljs-attr">"cursor"</span>: <span class="hljs-string">"abc123"</span>} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-VariantInventory" class="definition panel" data-traverse-target="definition-VariantInventory"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/VariantInventory"></a> - <p><code>VariantInventory</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Variant Inventory</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Field Name</th> - <th>Description</th> - </tr> - <tr> - <td data-property-name="aggregated"> <code>aggregated</code> - - <a href="#definition-Aggregated"><code>Aggregated</code></a> - </td> - <td> Aggregated product variant inventory information. This data may not be available if not set or if the store's Inventory Settings have disabled displaying stock levels on the storefront. </td> - </tr> - <tr> - <td data-property-name="isInStock"> <code>isInStock</code> - - <a href="#definition-Boolean"><code>Boolean!</code></a> - </td> - <td> Indicates whether this product is in stock. </td> - </tr> - <tr> - <td data-property-name="byLocation"> <code>byLocation</code> - - <a href="#definition-LocationConnection"><code>LocationConnection</code></a> - </td> - <td> Inventory by locations. </td> - </tr> - <tr> - <td colspan="2" class="no-top-border"> - <div class="field-arguments"> - <p class="field-arguments-header"> Arguments </p> - <div class="field-argument"> - <p class="field-argument-name"><code>locationEntityIds</code> - - <a href="#definition-Int"><code>[Int!]</code></a> default = <code>[]</code></p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>locationEntityCodes</code> - - <a href="#definition-String"><code>[String!]</code></a> default = <code>[]</code></p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>locationEntityTypeIds</code> - - <a href="#definition-String"><code>[String!]</code></a> default = <code>[]</code></p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>locationEntityServiceTypeIds</code> - - <a href="#definition-String"><code>[String!]</code></a> default = <code>[]</code></p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>distanceFilter</code> - - <a href="#definition-DistanceFilter"><code>DistanceFilter</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>before</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>after</code> - - <a href="#definition-String"><code>String</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>first</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - <div class="field-argument"> - <p class="field-argument-name"><code>last</code> - - <a href="#definition-Int"><code>Int</code></a> - </p> - </div> - </div> - </td> - </tr> - </table> - </section> - </div> - <div class="doc-examples"> - <section> - <h5>Example</h5> - <html> - <head></head> - <body><pre><code class="hljs language-json">{ - <span class="hljs-attr">"aggregated"</span>: Aggregated, - <span class="hljs-attr">"isInStock"</span>: <span class="hljs-literal">false</span>, - <span class="hljs-attr">"byLocation"</span>: LocationConnection -} -</code></pre> </body> - </html> - </section> - </div> - </div> - </div> - <div id="definition-countryCode" class="definition panel" data-traverse-target="definition-countryCode"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/countryCode"></a> - <p><code>countryCode</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Country Code</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Enum Value</th> - <th>Description</th> - </tr> - <tr> - <td> - <p><code>AW</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>AF</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>AO</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>AI</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>AX</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>AL</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>AD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>AE</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>AR</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>AM</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>AS</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>AQ</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>TF</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>AG</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>AU</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>AT</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>AZ</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BI</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BE</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BJ</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BQ</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BF</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BG</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BH</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BS</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BA</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BL</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BY</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BZ</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BM</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BO</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BR</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BB</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BN</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BT</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BV</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BW</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>CF</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>CA</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>CC</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>CH</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>CL</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>CN</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>CI</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>CM</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>CD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>CG</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>CK</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>CO</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>KM</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>CV</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>CR</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>CU</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>CW</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>CX</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>KY</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>CY</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>CZ</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>DE</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>DJ</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>DM</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>DK</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>DO</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>DZ</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>EC</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>EG</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ER</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>EH</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ES</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>EE</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ET</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>FI</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>FJ</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>FK</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>FR</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>FO</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>FM</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>GA</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>GB</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>GE</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>GG</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>GH</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>GI</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>GN</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>GP</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>GM</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>GW</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>GQ</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>GR</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>GD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>GL</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>GT</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>GF</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>GU</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>GY</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>HK</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>HM</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>HN</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>HR</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>HT</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>HU</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ID</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>IM</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>IN</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>IO</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>IE</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>IR</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>IQ</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>IS</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>IL</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>IT</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>JM</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>JE</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>JO</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>JP</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>KZ</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>KE</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>KG</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>KH</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>KI</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>KN</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>KR</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>KW</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>LA</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>LB</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>LR</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>LY</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>LC</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>LI</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>LK</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>LS</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>LT</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>LU</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>LV</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MO</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MF</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MA</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MC</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MG</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MV</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MX</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MH</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MK</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ML</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MT</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MM</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ME</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MN</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MP</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MZ</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MR</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MS</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MQ</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MU</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MW</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MY</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>YT</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>NA</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>NC</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>NE</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>NF</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>NG</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>NI</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>NU</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>NL</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>NO</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>NP</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>NR</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>NZ</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>OM</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>PK</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>PA</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>PN</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>PE</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>PH</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>PW</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>PG</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>PL</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>PR</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>KP</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>PT</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>PY</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>PS</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>PF</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>QA</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>RE</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>RO</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>RU</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>RW</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>SA</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>SD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>SN</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>SG</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>GS</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>SH</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>SJ</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>SB</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>SL</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>SV</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>SM</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>SO</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>PM</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>RS</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>SS</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ST</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>SR</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>SK</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>SI</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>SE</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>SZ</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>SX</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>SC</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>SY</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>TC</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>TD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>TG</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>TH</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>TJ</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>TK</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>TM</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>TL</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>TO</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>TT</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>TN</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>TR</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>TV</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>TW</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>TZ</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>UG</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>UA</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>UM</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>UY</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>US</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>UZ</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>VA</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>VC</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>VE</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>VG</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>VI</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>VN</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>VU</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>WF</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>WS</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>YE</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ZA</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ZM</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ZW</code></p> - </td> - <td> </td> - </tr> - </table> - </section> - </div> - </div> - </div> - <div id="definition-currencyCode" class="definition panel" data-traverse-target="definition-currencyCode"> - <div class="definition-tags"> - <a class="label" href="#tag-types">Types</a> - </div> - <h2 class="panel-title"> - <a name="/definitions/currencyCode"></a> - <p><code>currencyCode</code></p> - </h2> - <div class="doc-row"> - <div class="doc-copy"> - <section class="json-schema-description"> - <p>Currency Code</p> - </section> - <section class="json-schema-properties-blank"> - <table> - <tr> - <th>Enum Value</th> - <th>Description</th> - </tr> - <tr> - <td> - <p><code>ADP</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>AED</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>AFA</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>AFN</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ALK</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ALL</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>AMD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ANG</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>AOA</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>AOK</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>AON</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>AOR</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ARA</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ARL</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ARM</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ARP</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ARS</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ATS</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>AUD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>AWG</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>AZM</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>AZN</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BAD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BAM</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BAN</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BBD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BDT</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BEC</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BEF</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BEL</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BGL</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BGM</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BGN</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BGO</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BHD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BIF</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BMD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BND</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BOB</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BOL</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BOP</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BOV</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BRB</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BRC</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BRE</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BRL</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BRN</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BRR</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BRZ</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BSD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BTN</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BUK</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BWP</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BYB</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BYN</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BYR</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>BZD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>CAD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>CDF</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>CHE</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>CHF</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>CHW</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>CLE</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>CLF</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>CLP</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>CNX</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>CNY</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>COP</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>COU</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>CRC</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>CSD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>CSK</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>CUC</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>CUP</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>CVE</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>CYP</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>CZK</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>DDM</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>DEM</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>DJF</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>DKK</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>DOP</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>DZD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ECS</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ECV</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>EEK</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>EGP</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ERN</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ESA</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ESB</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ESP</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ETB</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>EUR</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>FIM</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>FJD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>FKP</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>FRF</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>GBP</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>GEK</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>GEL</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>GHC</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>GHS</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>GIP</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>GMD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>GNF</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>GNS</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>GQE</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>GRD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>GTQ</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>GWE</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>GWP</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>GYD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>HKD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>HNL</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>HRD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>HRK</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>HTG</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>HUF</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>IDR</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>IEP</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ILP</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ILR</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ILS</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>INR</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>IQD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ISJ</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>IRR</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ISK</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ITL</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>JMD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>JOD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>JPY</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>KES</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>KGS</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>KHR</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>KMF</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>KPW</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>KRH</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>KRO</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>KRW</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>KWD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>KYD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>KZT</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>LAK</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>LBP</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>LKR</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>LRD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>LSL</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>LTL</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>LTT</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>LUC</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>LUF</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>LUL</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>LVL</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>LVR</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>LYD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MAD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MAF</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MCF</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MDC</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MDL</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MGA</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MGF</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MKD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MKN</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MLF</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MMK</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MNT</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MOP</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MRO</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MTL</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MTP</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MUR</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MVP</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MVR</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MWK</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MXN</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MXP</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MXV</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MYR</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MZE</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MZM</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>MZN</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>NAD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>NGN</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>NIC</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>NIO</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>NLG</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>NOK</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>NPR</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>NZD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>OMR</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>PAB</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>PEI</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>PEN</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>PES</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>PGK</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>PHP</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>PKR</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>PLN</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>PLZ</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>PTE</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>PYG</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>QAR</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>RHD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ROL</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>RON</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>RSD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>RUB</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>RUR</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>RWF</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>SAR</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>SBD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>SCR</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>SDD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>SDG</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>SDP</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>SEK</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>SGD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>SHP</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>SIT</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>SKK</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>SLL</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>SOS</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>SRD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>SRG</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>SSP</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>STD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>SUR</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>SVC</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>SYP</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>SZL</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>THB</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>TJR</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>TJS</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>TMM</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>TMT</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>TND</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>TOP</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>TPE</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>TRL</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>TRY</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>TTD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>TWD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>TZS</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>UAH</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>UAK</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>UGS</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>UGX</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>USD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>USN</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>USS</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>UYI</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>UYP</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>UYU</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>UZS</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>VEB</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>VEF</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>VND</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>VNN</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>VUV</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>WST</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>XAF</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>XCD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>XEU</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>XFO</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>XFU</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>XOF</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>XPF</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>XRE</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>YDD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>YER</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>YUD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>YUM</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>YUN</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>YUR</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ZAL</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ZAR</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ZMK</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ZMW</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ZRN</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ZRZ</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ZWD</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ZWL</code></p> - </td> - <td> </td> - </tr> - <tr> - <td> - <p><code>ZWR</code></p> - </td> - <td> </td> - </tr> - </table> - </section> - </div> - </div> - </div> - <div class="doc-row no-margin"> - <div class="doc-copy doc-separator"> </div> - </div> - </article> - </div> - </div> -</div> diff --git a/docs/available-apis.mdx b/docs/available-apis.mdx deleted file mode 100644 index ba481d8bc..000000000 --- a/docs/available-apis.mdx +++ /dev/null @@ -1,64 +0,0 @@ -# Available APIs - -## Storefront APIs - -### REST - -Manage a shopper's cart and checkout and fetch order data via client-side JavaScript on BigCommerce [Stencil](/stencil-docs/getting-started/about-stencil) powered storefronts. - -[Learn more about storefront APIs](/api-docs/storefront/overview). - -### GraphQL - -Use GraphQL to query data for headless storefronts and BigCommerce [Stencil](/stencil-docs/getting-started/about-stencil) powered storefronts. - -[Learn more about the GraphQL Storefront API](/api-docs/storefront/graphql/graphql-storefront-api-overview) - -### Add to cart URLs - -Append query string parameters to product and `/cart.php` URLs to pre-select a SKU or add a product to cart. Use these parameters to build custom add to cart links and forms on BigCommerce hosted storefronts and remote sites (such as WordPress, blog posts, and social media). - -[Learn more about add to cart URLs](/api-docs/cart-and-checkout/add-to-cart-url). - -### Current Customer - -Identify logged-in customers securely via JavaScript. - -[Learn more about the current customer API](/api-docs/customers/current-customer-api). - -### Customer Login SSO - -Enable single sign-on for shoppers on BigCommerce hosted storefronts. - -[Learn more about the customer login API](/api-docs/customers/customer-login-api). - -## Management APIs - -### V2 REST API - -Mananage store resources from server-side code. - -Some **V2** resources are not yet exposed in the **V3 API**; however, for resources that are accessible via both APIs, the **V3 API** is recommended; it contains performance optimizations and [other improvements](#v3-rest-api). - -### V3 REST API - -Mananage store resources from server-side code. - -Interactions with the **V3** API are very similar to that of the **V2** API; however, the **V3** API introduces a number of improvements: -* Most tasks can be performed with fewer API calls (for example, a product with variants and custom fields can be created in a single request) -* Each **V3** resource includes a `meta` object, simplifying pagination -* **V3** Brands, Categories, Products, and Product Variants expose a [metafields](/docs/rest-management/catalog/product-metafields#create-a-product-metafield) resource for use by developers to store custom data. -* **V3** API is optimized for performance (in general, data can be sent, received, and processed faster via **V3**, relative to **V2**). - -[Learn more about the V3 API](/api-docs/getting-started/about-our-api). - -## Provider APIs - -Implement endpoints consumed by BigCommerce for custom integrations (ex: custom shipping carrier rates via `/rates`). - -[Learn more about the Shipping Provider API](/api-docs/store-management/shipping/shipping-provider-api). - -## Resources - -- [Deprecations and Sunsets](/api-docs/getting-started/deprecations-and-sunsets) -- [Difference between V2 and V3 Catalog REST APIs](/api-docs/store-management/catalog/v2-vs-v3) diff --git a/docs/customer-login-sso.mdx b/docs/customer-login-sso.mdx deleted file mode 100644 index 9cad1bf37..000000000 --- a/docs/customer-login-sso.mdx +++ /dev/null @@ -1,137 +0,0 @@ -# Customer Login SSO - -* **Host**: `{store_domain}/graphql` -* **Protocols**:`https` -* **Accepts**: `application/json` -* **Responds With**: `application/json` - - -Download Spec: [customer_login.json](#) -{/* https://bigcommerce.stoplight.io/api/v1/projects/bigcommerce/api-reference/nodes/reference/customer_login.yml?branch=master&deref=all&format=json */} - -Create a login URL for customer single sign-on. - -## Authentication - -To log in a customer using the Customer Login API, redirect the customer's browser to the following access point URL: - -```http copy - https://yourstore.example.com/login/token/{{TOKEN}} -``` - - -The `{{TOKEN}}` parameter is the `JWT` containing the payload data signed by your app's OAuth client secret. - -We recommend writing a script to generate a login token since the `JWT iat` (issued at) claim is only valid for 30 seconds. BigCommerce supplies helper methods for generating login tokens in our [API Client Libraries](/tools-resources). - - -### OAuth scopes - -| UI Name | Permission | Parameter | -|----|----|----| -| Customers | read-only | `store_v2_customers_read_only` | -| Customers | login | `store_v2_customers_login` | - - - -### JWT Header - -```json copy - { - "alg": "HS256", - "typ": "JWT" - } -``` - - -### JWT Payload - // example, schema - -### JWT Signature - -To create the signature, sign the encoded header, the encoded payload, and client_secret using the `HMAC SHA256` algorithm. - -```js copy - HMACSHA256( - base64UrlEncode(header) + "." + - base64UrlEncode(payload), - {{CLIENT_SECRET}} - ) -``` - - -## Node.js example - -Create `urlGenerator.js` node app and install dependencies. - -```shell copy - mkdir urlGenerator -``` - -```shell copy - cd urlGenerator -``` - -```shell copy - touch urlGenerator.js -``` - -```shell copy - npm init -``` - -```shell copy - npm install jsonwebtoken uuid -``` - -Paste the following into `urlGenerator/urlGenerator.js`. - -```js copy - const jwt = require('jsonwebtoken'); - const {v4: uuidv4} = require('uuid'); - - const clientId = "{{CLIENT_ID}}"; - const clientSecret = "{{CLIENT_SECRET}}"; - const customerId = "{{CUSTOMER_ID}}"; - const storeHash = "{{STORE_HASH}}"; - const storeUrl = "{{STORE_URL_ORIGIN}}"; - - function getLoginUrl(customerId, storeHash, storeUrl, clientId, clientSecret) { - const dateCreated = Math. round((new Date()). getTime() / 1000); - const payload = { - "iss": clientId, - "iat": dateCreated, - "jti": uuidv4(), - "operation": "customer_login", - "store_hash": storeHash, - "customer_id": customerId, - } - let token = jwt.sign(payload, clientSecret, {algorithm:'HS256'}); - return `${storeUrl}/login/token/${token}`; - }; - - const loginUrl = getLoginUrl(customerId, storeHash, storeUrl, clientId, clientSecret); - - console.log(loginUrl); -``` - - -Replace `{{CLIENT_ID}}` and other variables with your credentials, then run the app. - -```shell copy - node urlGenerator.js -``` - -You should receive a complete access point URL as an output. - -<Callout type="info"> - You are required to include the `channel_id` when using the login JWTs to redirect to an embedded checkout. Default value = 1. For more information, see the [Embedded Checkout Overview](/api-docs/storefronts/embedded-checkout/embedded-checkout-overview). -</Callout> - - -## Resources - -* [Customer Login SSO Generator with Ruby](https://github.com/jordanarldt/ruby-bc-customer-sso-generator/) -* [Customer Login API](/api-docs/customers/customer-login-api) -* [PHP Example](https://github.com/bigcommerce/bigcommerce-api-php/blob/master/src/Bigcommerce/Api/Client.php#L421) -* [Python Example](https://github.com/bigcommerce/bigcommerce-api-python/blob/master/bigcommerce/customer_login_token.py) diff --git a/docs/docs.mdx b/docs/docs.mdx new file mode 100644 index 000000000..79501d767 --- /dev/null +++ b/docs/docs.mdx @@ -0,0 +1,3 @@ +# Documentation in Markdown + +When there are docs in this repo written in Markdown or MDX, this is where they live. diff --git a/docs/storefront-graphql.mdx b/docs/storefront-graphql.mdx deleted file mode 100644 index 6ae0e3396..000000000 --- a/docs/storefront-graphql.mdx +++ /dev/null @@ -1,130 +0,0 @@ -# GraphQL Storefront API - -Use GraphQL to query data for headless storefronts and BigCommerce [Stencil](/stencil-docs/getting-started/about-stencil)-powered storefronts. - -## GraphQL Playground - -To access the GraphQL Storefront API Playground and documentation, [log in to your store](https://login.bigcommerce.com/deep-links/manage) and navigate to **Advanced Settings** **>** **Storefront API Playground**. - -If you don't yet have a store and would like to experiment making queries against a staging site, [visit the Dev Center's GraphQL Playground directly](/graphql-playground). - - -## GraphQL Explorer - -To explore Storefront nodes in an interactive graph, check out the [GraphQL Explorer](/graphql-explorer). - -## Authentication - - - -### Request tokens with REST API - -Create JWT tokens for authenticating cross-origin requests by making a `POST` request to the [Create a token](/docs/storefront-auth/tokens#create-a-token) endpoint. - -```http filename="Example request: Create a token" showLineNumbers copy -POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/storefront/api-token -X-Auth-Token: {{ACCESS_TOKEN}} -Content-Type: application/json -Accept: application/json - -{ - "channel_id": 1, - "expires_at": 1602288000, - "allowed_cors_origins": [ - "https://example.com" - ] -} -``` - -```json filename="Example response: Create a token" showLineNumbers copy -{ - "data": { - "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" - }, - "meta": {} -} -``` - -You can complete the GraphQL query call with any HTTP library. Use the `data.token` value from the preceding response as the `{{JWT}}` value in the `Authorization: Bearer {{JWT}}` header. - -```http filename="Example GraphQL query" showLineNumbers copy -POST /graphql -Authorization: Bearer {{JWT}} -Content-Type: application/json - -{ - "query": "{ site { ... } }" //graphql query string -} -``` - - -### Access tokens using Stencil objects - -Client scripts on BigCommerce [Stencil](/stencil-docs/getting-started/about-stencil)-powered storefronts can access a token with the `{{settings.storefront_api.token}}` Handlebars object. - -```handlebars filename="Example GraphQL query script with Stencil token" showLineNumbers copy -<script> -// nest within any conditional, such as onload - fetch('/graphql', { - method: 'POST', - headers: { - 'Content-Type': 'application/json', - 'Authorization': 'Bearer {{settings.storefront_api.token}}' - }, - body: JSON.stringify({ query: '{ site { ... } }' }) //graphql query string - }) - .then(data => console.log(data)) - .catch(error => console.error(error)); -</script> -``` - -### Customer impersonation tokens - -It's also possible to generate tokens for use in server-to-server interactions with a trusted consumer. Make a `POST` request to the [Create a customer impersonation token](/docs/storefront-auth/tokens/customer-impersonation-token#create-a-token) endpoint. - -```http filename="Example request: Create a customer impersonation token" showLineNumbers copy -POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/storefront/api-token-customer-impersonation -X-Auth-Token: {{ACCESS_TOKEN}} -Content-Type: application/json -Accept: application/json - -{ - "channel_id": 1, - "expires_at": 1602288000 -} - -``` - -```json filename="Example response: Create a customer impersonation token" showLineNumbers copy -{ - "data": { - "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" - }, - "meta": {} -} -``` - - -## Logging in a customer - -If you're using the Storefront API from a browser (for example, on top of your Stencil storefront) you can use the Customer Login mutation to log in a customer account with an email address and password (for server-side integrations, consider a customer impersonation token instead). This will set a session cookie in the browser which will authenticate the customer account on future requests: - -```graphql filename="Customer login mutation" showLineNumbers copy -mutation Login($email: String!, $pass: String!) { - login(email: $email, password: $pass) { - result - } -} -``` - -As a best practice, you should inject the password using GraphQL query variables. This prevents the password from being exposed in the query itself. In the [GraphQL Playground](/graphql-playground), you can set the variables for the request. [Learn more about GraphQL Storefront API Authentication](/api-docs/storefront/graphql/graphql-storefront-api-overview#authentication). - -## Error messages - -For a list of GraphQL error messages, see [API Status Codes](/api-docs/getting-started/api-status-codes#graphql-api-http-status-codes). - -## Resources - -* [GraphQL Storefront API Overview](/api-docs/storefront/graphql/graphql-storefront-api-overview) -* [GraphQL Playground](/graphql-playground) -* [GraphQL Explorer](/graphql-explorer) diff --git a/models/email_templates/_all.yml b/models/email_templates/_all.yml index 9fbc578f8..fb37bee75 100644 --- a/models/email_templates/_all.yml +++ b/models/email_templates/_all.yml @@ -658,7 +658,7 @@ properties: type: integer new_status: type: string - example: 'Incomplete, Pending, Shipped, Partially Shipped, Refunded, Cancelled, Declined, Awaiting Payment, Awaiting Pickup, Awaiting Shipment, Completed, Awaiting Fulfillment, Manual Verification Required, Disputed, Partially Refunded' + example: 'Incomplete, Pending, Shipped, Partially Shipped, Refunded, Cancelled, Declined, Awaiting Payment, Awaiting, Awaiting Shipment, Completed, Awaiting Fulfillment, Manual Verification Required, Disputed, Partially Refunded' new_formatted_status: type: string example: 'Shipment123, PendingOrder345, Cancelled0223222, Awaiting Payment in Store' @@ -708,6 +708,8 @@ properties: type: array items: type: object + description: Products that have been shipped, i.e., have been added to a consignment. + example: [Partially Shipped, Completed, Shipped, Refunded] properties: name: type: string @@ -732,6 +734,50 @@ properties: type: string link: type: string + unshipped_products: + type: array + description: Products that have not been shipped or added to a shipping consignment. + example: [Awaiting Fulfillment, Awaiting Shipment, Awaiting Pickup, Partially Shipped, Completed, Shipped, Refunded] + ready_for_pickup_products: + type: array + description: Products that have been added to a BOPIS pickup consignment and marked as ready for pickup. + items: + type: object + properties: + name: + type: string + sku: + type: string + quantity: + type: integer + thumbnail: + type: string + price: + type: string + brand: + type: string + picked_up_products: + type: array + description: Products that have been added to a BOPIS pickup consignment and marked as picked up. + items: + type: object + properties: + name: + type: string + sku: + type: string + quantity: + type: integer + thumbnail: + type: string + price: + type: string + brand: + type: string + pickup_methods: + type: array + items: + type: string store: type: object properties: @@ -798,42 +844,18 @@ properties: en: type: object properties: - title: - type: string - hello: - type: string - message: - type: string - details_title: - type: string - order_total: + prodname: type: string - date_placed: - type: string - payment_method: - type: string - total_refund: - type: string - products_shipped: - type: string - products_to_be_shipped: - type: string - tracking_title: - type: string - downloadable_items_title: - type: string - quantity: + example: "Product Name" + prodsku: type: string - download: - type: string - tracking_label: - type: string - no_tracking_numbers: - type: string - check_status: - type: string - go_shopping: + example: "Product SKU" + fr: + type: object + properties: + store: type: string + example: "Boutique" Account Created: title: Account Created Email Template description: Account created email triggers when a customer or store admin creates their account. @@ -1131,6 +1153,10 @@ properties: type: string customer_id: type: integer + pickup_methods: + type: array + items: + type: string date_placed: type: object properties: @@ -1260,6 +1286,122 @@ properties: items: type: object properties: {} + pickup: + type: array + items: + type: object + properties: + id: + type: integer + email: + type: string + phone: + type: string + instructions: + type: string + name: + type: string + location: + type: array + items: + type: object + properties: + name: + type: string + address_lines: + type: array + items: + type: string + city: + type: string + state: + type: string + country: + type: string + zip: + type: string + operating_hours: + type: array + items: + type: object + properties: + sunday: + type: object + properties: + is_open: + type: boolean + opening_time: + formatted: + type: string + closing_time: + formatted: + type: string + monday: + type: object + properties: + is_open: + type: boolean + opening_time: + formatted: + type: string + closing_time: + formatted: + type: string + tuesday: + type: object + properties: + is_open: + type: boolean + opening_time: + formatted: + type: string + closing_time: + formatted: + type: string + wednesday: + type: object + properties: + is_open: + type: boolean + opening_time: + formatted: + type: string + closing_time: + formatted: + type: string + thursday: + type: object + properties: + is_open: + type: boolean + opening_time: + formatted: + type: string + closing_time: + formatted: + type: string + friday: + type: object + properties: + is_open: + type: boolean + opening_time: + formatted: + type: string + closing_time: + formatted: + type: string + saturday: + type: object + properties: + is_open: + type: boolean + opening_time: + formatted: + type: string + closing_time: + formatted: + type: string payment: type: object properties: @@ -1267,8 +1409,16 @@ properties: type: boolean provider_name: type: string + deprecated: true offline_payment_message: type: string + payment_method: + type: string + provider: + type: object + properties: + name: + type: string gateway_amount: type: object description: Price value. Provided only if the payment method is offline. @@ -1352,6 +1502,7 @@ properties: type: integer show_immediate_download: type: boolean + store: type: object properties: @@ -1418,81 +1569,18 @@ properties: en: type: object properties: - comment_label: - type: string - order_id_line: - type: string - view_summary: - type: string - sepa: - type: string - description: A link to SEPA mandate and also receive this link embedded on email confirmation. - shipment_to_multiple_addresses: - type: string - shipping_immediate_download: - type: string - shipping_address_label: - type: string - immediate_download: - type: string - email: - type: string - billing_address_managed_by_amazon: + prodname: type: string - billing_address_label: + example: "Product Name" + prodsku: type: string - pending_payment: - type: string - how_to_pay: - type: string - pay_for_order_help: - type: string - order_total: - type: string - cart_items: - type: string - sku: - type: string - quantity: - type: string - item_price: - type: string - item_total: - type: string - payment_method: - type: string - no_payment_taken_in_test_mode: - type: string - download_files: - type: string - preorder: - type: string - download_available_after_payment: - type: string - shipped_to: - type: string - shipping_discount: - type: string - thanks_for_your_order: - type: string - your_order_contains: - type: string - shipping_method: - type: string - shipping_to_address: - type: string - your_order_will_be_shipped_by: - type: string - total_cost: - type: string - items: - type: string - total: - type: string - price: - type: string - email_address: + example: "Product SKU" + fr: + type: object + properties: + store: type: string + example: "Boutique" Order Notification: title: Order Notification Email Template description: Order notification email triggers when a merchant or store admin adds a message to an order. @@ -1583,6 +1671,244 @@ properties: type: string go_shopping: type: string + Order ready for pickup: + title: Order Ready for Pick-up Email Template + description: Order ready for pick-up email triggers when a customer or store admin creates a pick-up order. + type: object + properties: + order: + type: object + properties: + id: + type: integer + account_order_status_url: + type: string + products: + type: array + items: + type: object + properties: + id: + type: integer + quantity: + type: integer + name: + type: string + sku: + type: string + thumbnail: + type: string + options: + type: array + properties: + Size: + type: string + attribute_lines: + type: array + description: A list of strings that represents product variant options. + items: + type: object + properties: {} + configurable_fields: + type: array + description: Object array with properties name and value. + items: + type: object + properties: {} + pickup: + type: array + items: + type: object + properties: + id: + type: integer + email: + type: string + phone: + type: string + instructions: + type: string + name: + type: string + location: + type: array + items: + type: object + properties: + name: + type: string + address_lines: + type: array + items: + type: string + city: + type: string + state: + type: string + country: + type: string + zip: + type: string + operating_hours: + type: array + items: + type: object + properties: + sunday: + type: object + properties: + is_open: + type: boolean + opening_time: + formatted: + type: string + closing_time: + formatted: + type: string + monday: + type: object + properties: + is_open: + type: boolean + opening_time: + formatted: + type: string + closing_time: + formatted: + type: string + tuesday: + type: object + properties: + is_open: + type: boolean + opening_time: + formatted: + type: string + closing_time: + formatted: + type: string + wednesday: + type: object + properties: + is_open: + type: boolean + opening_time: + formatted: + type: string + closing_time: + formatted: + type: string + thursday: + type: object + properties: + is_open: + type: boolean + opening_time: + formatted: + type: string + closing_time: + formatted: + type: string + friday: + type: object + properties: + is_open: + type: boolean + opening_time: + formatted: + type: string + closing_time: + formatted: + type: string + saturday: + type: object + properties: + is_open: + type: boolean + opening_time: + formatted: + type: string + closing_time: + formatted: + type: string + store: + type: object + properties: + name: + type: string + domain_name: + type: string + logo: + type: object + properties: + title: + type: string + name: + type: string + url: + type: string + ssl_path: + type: string + cdn_path: + type: string + image_directory: + type: string + img_path: + type: string + path_normal: + type: string + description: 'Path to the store (i.e., domain + protocol)' + path: + type: string + address: + type: string + language: + type: object + properties: + code: + type: string + direction: + type: string + description: 'Left to right or right to left, depending on the language' + customer: + type: object + properties: + first_name: + type: string + full_name: + type: string + email: + type: string + group: + type: array + items: + type: object + properties: + name: + type: string + misc: + type: object + properties: + year: + type: integer + translations: + type: object + properties: + en: + type: object + properties: + prodname: + type: string + example: "Product Name" + prodsku: + type: string + example: "Product SKU" + fr: + type: object + properties: + store: + type: string + example: "Boutique" Sign in Link Request: title: Sign in Link Request Email Template description: Sign-in request email triggers when an existing customer requests passwordless login while checking out. diff --git a/models/email_templates/combined/README.md b/models/email_templates/combined/README.md new file mode 100644 index 000000000..3d6690d38 --- /dev/null +++ b/models/email_templates/combined/README.md @@ -0,0 +1,32 @@ +# Email Template Objects + +Object schemas for handlebars email templates. + +## Directory structure + +```shell +. +├── data # json data for generating and updating yaml schema +├── _all.yml # Groups models together for docs +├── account_details_changed_email.yml # Individual email template models +├── ... +``` + +## Updating models + +To generate a new model from json data and overwrite the existing schema file: + +1. Copy and paste template `data-*.json` from [localization-tools](https://github.com/bigcommerce/localization-tools/blob/master/email-check/modules/email-templates/types/abandoned_cart_email/data-0.json) to `models/_json/email_templates`. +2. Use `models/json2schema.py` to convert the json data to a yaml schema. + +Example: + +```bash +cat data.json | python json2schema.py > schema.yml +``` + +Bash for overwriting all email template models: + +```bash +for f in models/email_templates/data/*.json; do cat $f | python models/json2schema.py > ${f%.*}.yml; mv ${f%.*}.yml models/email_templates/; done +``` \ No newline at end of file diff --git a/models/email_templates/combined/abandoned_cart_email.yml b/models/email_templates/combined/abandoned_cart_email.yml new file mode 100644 index 000000000..3c283fec8 --- /dev/null +++ b/models/email_templates/combined/abandoned_cart_email.yml @@ -0,0 +1,169 @@ +title: Abandoned Cart Email Template +description: Abandoned cart email triggers when a shopper doesnʼt complete an order. +type: object +properties: + notification: + type: array + items: + type: object + properties: + unsubscribe_link: + type: string + checkout_link: + type: string + coupon: + type: array + items: + type: object + properties: + code: + type: string + type: + type: array + items: + type: object + properties: + value: + type: string + formatted: + type: string + amount: + type: array + items: + type: object + properties: + value: + type: number + format: float + formatted: + type: string + cart: + type: array + items: + type: object + properties: + products: + type: array + items: + type: object + properties: + type: array + items: + type: object + properties: + id: + type: number + url: + type: string + name: + type: string + quantity: + type: integer + sku: + type: string + thumbnail: + type: string + attributes: + type: array + items: + type: object + properties: + type: array + items: + type: object + properties: + name: + type: string + value: + type: string + price: + type: array + items: + type: object + properties: + value: + type: number + format: float + formatted: + type: string + type: + type: array + items: + type: object + properties: + value: + type: integer + formatted: + type: string + store: + type: array + items: + type: object + properties: + name: + type: string + domain_name: + type: string + logo: + type: array + items: + type: object + properties: + title: + type: string + name: + type: string + url: + type: string + ssl_path: + type: string + cdn_path: + type: string + image_directory: + type: string + img_path: + type: string + path_normal: + type: string + path: + type: string + address: + type: string + phone_number: + type: string + language: + type: array + items: + type: object + properties: + code: + type: string + direction: + type: string + customer: + type: array + items: + type: object + properties: + first_name: + type: string + full_name: + type: string + email: + type: string + group: + type: array + items: + type: object + properties: + id: + type: number + name: + type: string + misc: + type: array + items: + type: object + properties: + year: + type: integer diff --git a/models/email_templates/combined/abandoned_cart_email_deprecated.yml b/models/email_templates/combined/abandoned_cart_email_deprecated.yml new file mode 100644 index 000000000..1cd67fbd6 --- /dev/null +++ b/models/email_templates/combined/abandoned_cart_email_deprecated.yml @@ -0,0 +1,119 @@ +title: Abandoned Cart Email Template (Deprecated) +description: Abandoned cart email triggers when a shopper doesnʼt complete an order. +type: object +deprecated: true +properties: + abandoned_cart: + type: object + title: deprecated + deprecated: true + properties: + body: + type: string + unsubscribe_link: + type: string + store: + type: object + deprecated: true + properties: + name: + type: string + domain_name: + type: string + logo: + type: object + deprecated: true + properties: + title: + type: string + name: + type: string + url: + type: string + ssl_path: + type: string + cdn_path: + type: string + image_directory: + type: string + img_path: + type: string + path_normal: + type: string + description: 'Path to the store (i.e., domain + protocol)' + path: + type: string + address: + type: string + language: + type: object + properties: + code: + type: string + direction: + type: string + description: 'Left to right or right to left, depending on the language' + customer: + type: object + deprecated: true + properties: + first_name: + type: string + full_name: + type: string + email: + type: string + group: + type: array + items: + type: object + properties: + name: + type: string + misc: + type: object + deprecated: true + properties: + year: + type: integer + translations: + type: object + deprecated: true + properties: + en: + type: object + properties: + unsubscribe: + type: string +examples: + Abandoned Cart example (deprecated): + value: + abandoned_cart: + body: You recently visited our online store and we noticed that you didnʼt complete your order.\n <br>To complete your order right now, just click on the link below:\n <a href=\"example.com/complete-order\">Complete your order</a> + unsubscribe_link: 'example.com/unsubscribe' + store: + name: My Dev Store 97434969 + domain_name: my-dev-store-97434969.store.bcdev + logo: + title: [= My Dev Store 97434969 =] + name: avatar-2020_1612860757__16350.jpeg + url: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96/product_images/avatar-2020_1612860757__16350.jpeg' + ssl_path: 'https://my-dev-store-97434969.store.bcdev' + cdn_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96' + image_directory: product_images + img_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/r08d84bb67d250c7624502ed76d8e0bafb1a5cacf/g-themes/ClassicNext/images' + path_normal: 'https://my-dev-store-97434969.store.bcdev' + path: 'https://my-dev-store-97434969.store.bcdev' + address: '123 Fake St, Dallas, TX 75225' + language: + code: en + direction: ltr + customer: + first_name: John + full_name: John Jr + email: 'john.f@example.com' + misc: + year: 2021 + translations: + en: + unsubscribe: '<a href=\"example.com/unsubscribe\">Unsubscribe</a> from future emails like this.' diff --git a/models/email_templates/combined/account_details_changed_email.yml b/models/email_templates/combined/account_details_changed_email.yml new file mode 100644 index 000000000..2bce30060 --- /dev/null +++ b/models/email_templates/combined/account_details_changed_email.yml @@ -0,0 +1,128 @@ +title: Account Settings Edited Email Template +description: Account settings email triggers when the store admin or a customer edits account settings. +type: object +properties: + details_changed: + type: object + properties: + fields: + type: array + items: + type: string + store: + type: object + properties: + name: + type: string + domain_name: + type: string + logo: + type: object + properties: + title: + type: string + name: + type: string + url: + type: string + ssl_path: + type: string + cdn_path: + type: string + image_directory: + type: string + img_path: + type: string + path_normal: + type: string + description: 'Path to the store (i.e., domain + protocol)' + path: + type: string + address: + type: string + language: + type: object + properties: + code: + type: string + direction: + type: string + description: 'Left to right or right to left, depending on the language' + customer: + type: object + properties: + first_name: + type: string + full_name: + type: string + email: + type: string + group: + type: array + items: + type: object + properties: + name: + type: string + misc: + type: object + properties: + year: + type: integer + translations: + type: object + properties: + en: + type: object + properties: + title: + type: string + hello: + type: string + message: + type: string + warning: + type: string + thanks: + type: string + security: + type: string + go_shopping: + type: string +example: + details_changed: + fields: + - Email + - Password + store: + name: My Dev Store 97434969 + domain_name: 'my-dev-store-97434969.store.bcdev' + logo: + title: '[= My Dev Store 97434969 =]' + name: avatar-2020_1612860757__16350.jpeg + url: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96/product_images/avatar-2020_1612860757__16350.jpeg' + ssl_path: 'https://my-dev-store-97434969.store.bcdev' + cdn_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96' + image_directory: product_images + img_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/r08d84bb67d250c7624502ed76d8e0bafb1a5cacf/g-themes/ClassicNext/images' + path_normal: 'https://my-dev-store-97434969.store.bcdev' + path: 'https://my-dev-store-97434969.store.bcdev' + address: + language: + code: en + direction: ltr + customer: + first_name: John + full_name: John Jr + email: 'john.f@example.com' + misc: + year: 2021 + translations: + en: + title: Your {{name}} account details have changed + hello: Hello {{name}}, + message: 'We wanted to let you know that the following details have been changed on your <a href=\{{link}}\ target=\_blank\>{{name}}</a> account:' + warning: 'If you made the changes yourself, please disregard this email. If not, please contact the store immediately through their website: <a href=\{{link}}\ target=\_blank\>{{domain}}</a>.' + thanks: Thanks, + security: The BigCommerce Security Team + go_shopping: Go shopping diff --git a/models/email_templates/combined/account_reset_password_email.yml b/models/email_templates/combined/account_reset_password_email.yml new file mode 100644 index 000000000..5e60b6431 --- /dev/null +++ b/models/email_templates/combined/account_reset_password_email.yml @@ -0,0 +1,112 @@ +title: Password Reset Email Template +description: Password reset email triggers when a customer resets their account password on the customer details page. +type: object +properties: + reset_password: + type: object + properties: + link: + type: string + store: + type: object + properties: + name: + type: string + domain_name: + type: string + logo: + type: object + properties: + title: + type: string + name: + type: string + url: + type: string + ssl_path: + type: string + cdn_path: + type: string + image_directory: + type: string + img_path: + type: string + path_normal: + type: string + description: 'Path to the store (i.e., domain + protocol)' + path: + type: string + address: + type: string + language: + type: object + properties: + code: + type: string + direction: + type: string + description: 'Left to right or right to left, depending on the language' + customer: + type: object + properties: + first_name: + type: string + full_name: + type: string + email: + type: string + group: + type: array + items: + type: object + properties: + name: + type: string + misc: + type: object + properties: + year: + type: integer + translations: + type: object + properties: + en: + type: object + properties: + title: + type: string + message: + type: string + go_shopping: + type: string +example: + reset_password: + link: #reset-password-link + store: + name: My Dev Store 97434969 + domain_name: my-dev-store-97434969.store.bcdev + logo: + title: [= My Dev Store 97434969 =] + name: avatar-2020_1612860757__16350.jpeg + url: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96/product_images/avatar-2020_1612860757__16350.jpeg' + ssl_path: 'https://my-dev-store-97434969.store.bcdev' + cdn_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96' + image_directory: product_images + img_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/r08d84bb67d250c7624502ed76d8e0bafb1a5cacf/g-themes/ClassicNext/images' + path_normal: 'https://my-dev-store-97434969.store.bcdev' + path: 'https://my-dev-store-97434969.store.bcdev' + address: '123 Fake St, Dallas, TX 75225' + language: + code: en + direction: ltr + customer: + first_name: John, + full_name: John Jr, + email: 'john.f@example.com' + misc: + year: 2021 + translations: + en: + title: Change your password for {{name}} + message: 'To change your customer account password at {{store}} please click this link or copy and paste it into your browser:' + go_shopping: Go shopping diff --git a/models/email_templates/combined/combined_order_status_email.yml b/models/email_templates/combined/combined_order_status_email.yml new file mode 100644 index 000000000..bc64b12a9 --- /dev/null +++ b/models/email_templates/combined/combined_order_status_email.yml @@ -0,0 +1,260 @@ +title: Order Status Update Email Template +description: Order status update email triggers when the status of an order changes. +type: object +properties: + order: + type: object + properties: + id: + type: integer + new_status: + type: string + example: 'Incomplete, Pending, Shipped, Partially Shipped, Refunded, Cancelled, Declined, Awaiting Payment, Awaiting Pickup, Awaiting Shipment, Completed, Awaiting Fulfillment, Manual Verification Required, Disputed, Partially Refunded' + new_formatted_status: + type: string + example: 'Shipment123, PendingOrder345, Cancelled0223222, Awaiting Payment in Store' + total: + type: object + properties: + value: + type: float + formatted: + type: string + refund: + type: object + properties: + value: + type: float + formatted: + type: string + date_placed: + type: object + properties: + value: + type: integer + formatted: + type: string + payment_method: + type: string + link: + type: string + customer_name: + type: string + downloadable_products: + type: array + items: + type: object + properties: + name: + type: string + options: + type: string + quantity: + type: integer + link: + type: string + thumbnail: + type: string + products: + type: array + items: + type: object + properties: + name: + type: string + sku: + type: string + price: + type: string + quantity: + type: integer + thumbnail: + type: string + brand: + type: string + tracking: + type: array + items: + type: object + properties: + id: + type: string + shipping_method: + type: string + link: + type: string + store: + type: object + properties: + name: + type: string + domain_name: + type: string + logo: + type: object + properties: + title: + type: string + name: + type: string + url: + type: string + ssl_path: + type: string + cdn_path: + type: string + image_directory: + type: string + img_path: + type: string + path_normal: + type: string + description: 'Path to the store (i.e., domain + protocol)' + path: + type: string + address: + type: string + language: + type: object + properties: + code: + type: string + direction: + type: string + description: 'Left to right or right to left, depending on the language' + customer: + type: object + properties: + first_name: + type: string + full_name: + type: string + email: + type: string + group: + type: array + items: + type: object + properties: + name: + type: string + misc: + type: object + properties: + year: + type: integer + translations: + type: object + properties: + en: + type: object + properties: + title: + type: string + hello: + type: string + message: + type: string + details_title: + type: string + order_total: + type: string + date_placed: + type: string + payment_method: + type: string + total_refund: + type: string + products_shipped: + type: string + products_to_be_shipped: + type: string + tracking_title: + type: string + downloadable_items_title: + type: string + quantity: + type: string + download: + type: string + tracking_label: + type: string + no_tracking_numbers: + type: string + check_status: + type: string + go_shopping: + type: string +example: + order: + id: 1 + new_status: Awaiting Fulfillment + total: + value: 10 + formatted: $10.00 USD + refund: + value: 0 + formatted: + date_placed: + value: 1614615796 + formatted: 03/01/2121 + payment_method: Store Credit + link: '#status-link' + customer_name: John Cena + downloadable_products: + name: Journal + options: + quantity: 1 + link: '#downloadable-link' + products: + name: Test product + sku: FA44 + quantity: 11 + tracking: + id: 123BC + shipping_method: DHL + link: '#example.com' + store: + name: My Dev Store 97434969 + domain_name: 'my-dev-store-97434969.store.bcdev' + logo: + title: '= My Dev Store 97434969 =' + name: 'avatar-2020_1612860757__16350.jpeg' + url: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96/product_images/avatar-2020_1612860757__16350.jpeg' + ssl_path: 'https://my-dev-store-97434969.store.bcdev' + cdn_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96' + image_directory: product_images + img_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/r08d84bb67d250c7624502ed76d8e0bafb1a5cacf/g-themes/ClassicNext/images' + path_normal: 'https://my-dev-store-97434969.store.bcdev' + path: 'https://my-dev-store-97434969.store.bcdev' + address: + language: + code: en + direction: ltr + customer: + first_name: John + full_name: John Jr + email: 'john.f@example.com' + misc: + year: 2023 + translations: + en: + title: Order status changed + hello: Hi + message: 'The status of your order #id has changed to <strong>{{status}}</strong>.' + details_title: Order details + order_total: 'Order total:' + date_placed: 'Date placed:' + payment_method: 'Payment method:' + total_refund: 'Total refunded:' + products_shipped: Products shipped + products_to_be_shipped: Products to be shipped + tracking_title: Tracking information + downloadable_items_title: Downloadable items + quantity: 'Qty:' + download: Download file + tracking_label: Tracking Link + no_tracking_numbers: No tracking numbers are assigned to your order yet + check_status: Check order status + go_shopping: Go shopping + diff --git a/models/email_templates/combined/create_account_email.yml b/models/email_templates/combined/create_account_email.yml new file mode 100644 index 000000000..92cd78317 --- /dev/null +++ b/models/email_templates/combined/create_account_email.yml @@ -0,0 +1,128 @@ +title: Account Created Email Template +description: Account created email triggers when a customer or store admin creates their account. +type: object +properties: + store: + type: object + properties: + name: + type: string + domain_name: + type: string + logo: + type: object + properties: + title: + type: string + name: + type: string + url: + type: string + ssl_path: + type: string + cdn_path: + type: string + image_directory: + type: string + img_path: + type: string + path_normal: + type: string + description: 'Path to the store (i.e., domain + protocol)' + path: + type: string + address: + type: string + language: + type: object + properties: + code: + type: string + direction: + type: string + description: 'Left to right or right to left, depending on the language' + customer: + type: object + properties: + first_name: + type: string + full_name: + type: string + email: + type: string + group: + type: array + items: + type: object + properties: + name: + type: string + misc: + type: object + properties: + year: + type: integer + translations: + type: object + properties: + en: + type: object + properties: + title: + type: string + hello: + type: string + message: + type: string + details_title: + type: string + email_label: + type: string + password_label: + type: string + password_placeholder: + type: string + sign_in: + type: string + help: + type: string + go_shopping: + type: string +example: + store: + name: My Dev Store 97434969 + domain_name: my-dev-store-97434969.store.bcdev + logo: + title: [= My Dev Store 97434969 =] + name: avatar-2020_1612860757__16350.jpeg + url: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96/product_images/avatar-2020_1612860757__16350.jpeg' + ssl_path: 'https://my-dev-store-97434969.store.bcdev' + cdn_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96' + image_directory: product_images + img_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/r08d84bb67d250c7624502ed76d8e0bafb1a5cacf/g-themes/ClassicNext/images' + path_normal: 'https://my-dev-store-97434969.store.bcdev' + path: 'https://my-dev-store-97434969.store.bcdev' + address: '123 Fake St, Dallas, TX 75225' + language: + code: en + direction: ltr + customer: + first_name: John + full_name: John Jr + email: john.f@example.com + misc: + year: 2021 + translations: + en: + title: Thanks for registering at {{store}} + hello: Hello {{name}}. + message: Thank you for creating your account at {{name}}. + details_title: Account details + email_label: 'Email Address:' + password_label: 'Password:' + password_placeholder: [The password you specified] + sign_in: Sign in to account + help: If you have any questions regarding your account, click 'Reply' in your email client and we'll be only too happy to help. + go_shopping: Go shopping + + diff --git a/models/email_templates/combined/create_guest_account_email.yml b/models/email_templates/combined/create_guest_account_email.yml new file mode 100644 index 000000000..486291670 --- /dev/null +++ b/models/email_templates/combined/create_guest_account_email.yml @@ -0,0 +1,114 @@ +title: Create Guest Account Email Template +description: Guest account created email triggers when a customer or store admin creates a guest account. +type: object +properties: + guest_account: + type: object + properties: + link: + type: string + store: + type: object + properties: + name: + type: string + domain_name: + type: string + logo: + type: object + properties: + title: + type: string + name: + type: string + url: + type: string + ssl_path: + type: string + cdn_path: + type: string + image_directory: + type: string + img_path: + type: string + path_normal: + type: string + description: 'Path to the store (i.e., domain + protocol)' + path: + type: string + address: + type: string + language: + type: object + properties: + code: + type: string + direction: + type: string + description: 'Left to right or right to left, depending on the language' + customer: + type: object + properties: + first_name: + type: string + full_name: + type: string + email: + type: string + misc: + type: object + properties: + year: + type: integer + translations: + type: object + properties: + en: + type: object + properties: + title: + type: string + hello: + type: string + message: + type: string + instruction: + type: string + help: + type: string + go_shopping: + type: string +examples: + guest_account: + link: 'https://example.com/reset-password' + store: + name: My Dev Store 97434969 + domain_name: my-dev-store-97434969.store.bcdev + logo: + title: [= My Dev Store 97434969 =] + name: avatar-2020_1612860757__16350.jpeg + url: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96/product_images/avatar-2020_1612860757__16350.jpeg' + ssl_path: 'https://my-dev-store-97434969.store.bcdev' + cdn_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96' + image_directory: product_images + img_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/r08d84bb67d250c7624502ed76d8e0bafb1a5cacf/g-themes/ClassicNext/images' + path_normal: 'https://my-dev-store-97434969.store.bcdev' + path: 'https://my-dev-store-97434969.store.bcdev' + address: '123 Fake St, Dallas, TX 75225' + language: + code: en + direction: ltr + customer: + first_name: John + full_name: John Jr + email: 'john.f@example.com' + misc: + year: 2021 + translations: + en: + title: Welcome to {{name}} + hello: Hello {{name}}, + message: For your convenience, we've created you an account on {{store}} so you can check the status of your order and checkout quicker in the future. + instruction: 'To login you will need to follow the link below to nominate your password:' + help: If you have any questions regarding your account, click 'Reply' in your email client and we'll be only too happy to help. + go_shopping: Go shopping diff --git a/models/email_templates/combined/gift_certificate_email.yml b/models/email_templates/combined/gift_certificate_email.yml new file mode 100644 index 000000000..e77e2361f --- /dev/null +++ b/models/email_templates/combined/gift_certificate_email.yml @@ -0,0 +1,155 @@ +title: Gift Certificate Email Template +description: Gift certificate recipient email triggers when a customer purchases a gift certificate. +type: object +properties: + certificate: + type: object + properties: + code: + type: string + to_name: + type: string + to_email: + type: string + from_name: + type: string + from_email: + type: string + amount: + type: string + redeem_link: + type: string + expiry_date: + type: object + properties: + formatted: + type: string + value: + type: integer + store: + type: object + properties: + name: + type: string + domain_name: + type: string + logo: + type: object + properties: + title: + type: string + name: + type: string + url: + type: string + ssl_path: + type: string + cdn_path: + type: string + image_directory: + type: string + img_path: + type: string + path_normal: + type: string + description: 'Path to the store (i.e., domain + protocol)' + path: + type: string + address: + type: string + language: + type: object + properties: + code: + type: string + direction: + type: string + description: 'Left to right or right to left, depending on the language' + customer: + type: object + properties: + first_name: + type: string + full_name: + type: string + email: + type: string + group: + type: array + items: + type: object + properties: + name: + type: string + misc: + type: object + properties: + year: + type: integer + translations: + type: object + properties: + en: + type: object + properties: + title: + type: string + hello: + type: string + message: + type: string + expiry_info: + type: string + instruction: + type: string + attached: + type: string + warning: + type: string + go_shopping: + type: string +example: + certificate: + code: FA-21465 + to_name: John + to_email: 'john.f@example.com' + from_name: John Wick + from_email: 'johnwick@example.com' + amount: '12.34' + redeem_link: '#redeem-link' + expiry_date: + formatted: 03/01/2121 + value: 1614615821 + store: + name: My Dev Store 97434969 + domain_name: my-dev-store-97434969.store.bcdev + logo: + title: [= My Dev Store 97434969 =] + name: avatar-2020_1612860757__16350.jpeg + url: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96/product_images/avatar-2020_1612860757__16350.jpeg' + ssl_path: 'https://my-dev-store-97434969.store.bcdev' + cdn_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96' + image_directory: product_images + img_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/r08d84bb67d250c7624502ed76d8e0bafb1a5cacf/g-themes/ClassicNext/images' + path_normal: 'https://my-dev-store-97434969.store.bcdev' + path: 'https://my-dev-store-97434969.store.bcdev' + address: '123 Fake St, Dallas, TX 75225 USA' + language: + code: en + direction: ltr + customer: + first_name: John + full_name: John Jr + email: 'john.f@example.com' + misc: + year: 2021 + translations: + en: + title: You have received a Gift Certificate for {{name}} + hello: Dear {{name}}, + message: '{{from_name}} ({{from_email}}) has sent you a {{amount}} gift certificate for <a href=\{{path}}\>{{name]}</a>.' + expiry_info: You have until {{date}} to use this gift certificate before it expires. + instruction: 'For instructions on how to redeem your gift certificate please <a href=\{{link}}\>click here</a>.' + attached: Your gift certificate is attached to this email. + warning: Please download or print a copy of your gift certificate for safe keeping as gift certificates are non-transferable. + go_shopping: Go shopping diff --git a/models/email_templates/combined/global.yml b/models/email_templates/combined/global.yml new file mode 100644 index 000000000..16140df2d --- /dev/null +++ b/models/email_templates/combined/global.yml @@ -0,0 +1,88 @@ +title: Global Email Template Object +description: Data objects across all email templates. +type: object +properties: + store: + type: object + properties: + name: + type: string + domain_name: + type: string + logo: + type: object + properties: + title: + type: string + name: + type: string + url: + type: string + ssl_path: + type: string + cdn_path: + type: string + image_directory: + type: string + img_path: + type: string + path_normal: + type: string + description: 'Path to the store (i.e., domain + protocol)' + path: + type: string + address: + type: string + language: + type: object + properties: + code: + type: string + direction: + type: string + description: 'Left to right or right to left, depending on the language' + customer: + type: object + properties: + first_name: + type: string + full_name: + type: string + email: + type: string + group: + type: array + items: + type: object + properties: + name: + type: string + misc: + type: object + properties: + year: + type: integer +example: + store: + name: string, + domain_name: string + logo: + title: string + name: string + url: string + ssl_path: string + cdn_path: string + image_directory: string + img_path: string + path_normal: string + path: string + address: string + language: + code: string + direction: string + customer: + first_name: string + full_name: string + email: string + misc: + year: int diff --git a/models/email_templates/combined/invoice_email.yml b/models/email_templates/combined/invoice_email.yml new file mode 100644 index 000000000..4c2113a9c --- /dev/null +++ b/models/email_templates/combined/invoice_email.yml @@ -0,0 +1,523 @@ +title: Order Email Template +description: Order email triggers when a customer or store admin creates an order. +type: object +properties: + order: + type: object + properties: + id: + type: integer + customer_message: + type: string + customer_id: + type: integer + date_placed: + type: object + properties: + formatted: + type: string + value: + type: integer + account_order_status_url: + type: string + shipping: + type: object + properties: + methods: + type: array + items: + type: object + properties: + address: + type: object + properties: + email: + type: string + phone: + type: string + first_name: + type: string + last_name: + type: string + company: + type: string + country: + type: string + city: + type: string + state: + type: string + zip: + type: string + address_lines: + type: array + items: + type: object + properties: + custom_fields: + type: array + items: + type: object + properties: + products: + type: array + items: + type: object + properties: + name: + type: string + quantity: + type: integer + sku: + type: string + address_lines: + type: array + items: + type: object + properties: + address_id: + type: integer + options: + type: object + properties: + Size: + type: string + download_url: + type: string + thumbnail: + type: string + brand: + type: string + event: + type: object + properties: + name: + type: string + date: + type: object + properties: + value: + type: integer + formatted: + type: string + price: + type: object + properties: + value: + type: float + formatted: + type: string + total: + type: object + properties: + value: + type: float + formatted: + type: string + preorder: + type: object + properties: + is_preorder: + type: boolean + message: + type: string + date: + type: object + properties: + value: + type: integer + formatted: + type: string + attribute_lines: + type: array + description: A list of strings that represents product variant options. + items: + type: object + properties: + configurable_fields: + type: array + description: Object array with properties name and value. + items: + type: object + properties: + payment: + type: object + properties: + is_test: + type: boolean + provider_name: + type: string + offline_payment_message: + type: string + gateway_amount: + type: object + description: Price value. Provided only if the payment method is offline. + properties: + formatted: + type: string + value: + type: float + billing: + type: object + properties: + is_managed_by_amazon: + type: boolean + address: + type: object + properties: + email: + type: string + phone: + type: string + first_name: + type: string + last_name: + type: string + company: + type: string + country: + type: string + city: + type: string + state: + type: string + zip: + type: string + address_lines: + type: array + items: + type: object + properties: + custom_fields: + type: array + items: + type: object + properties: + total_rows: + type: array + items: + type: object + properties: + label: + type: string + price: + type: object + properties: + value: + type: float + formatted: + type: string + shipping_discounts: + type: array + items: + type: object + properties: + total_cost: + type: object + properties: + formatted: + type: string + value: + type: float + meta: + type: object + properties: + mandate_url: + type: string + description: Link to the confirmation page in Stripe + mandate_tag: + type: string + description: Short name of the payment document + shipping_addresses_num: + type: integer + show_immediate_download: + type: boolean + store: + type: object + properties: + name: + type: string + domain_name: + type: string + logo: + type: object + properties: + title: + type: string + name: + type: string + url: + type: string + ssl_path: + type: string + cdn_path: + type: string + image_directory: + type: string + img_path: + type: string + path_normal: + type: string + description: 'Path to the store (i.e., domain + protocol)' + path: + type: string + address: + type: string + language: + type: object + properties: + code: + type: string + direction: + type: string + description: 'Left to right or right to left, depending on the language' + customer: + type: object + properties: + first_name: + type: string + full_name: + type: string + email: + type: string + group: + type: array + items: + type: object + properties: + name: + type: string + misc: + type: object + properties: + year: + type: integer + translations: + type: object + properties: + en: + type: object + properties: + comment_label: + type: string + order_id_line: + type: string + view_summary: + type: string + sepa: + type: string + description: A link to SEPA mandate and also receive this link embedded on email confirmation. + shipment_to_multiple_addresses: + type: string + shipping_immediate_download: + type: string + shipping_address_label: + type: string + immediate_download: + type: string + email: + type: string + billing_address_managed_by_amazon: + type: string + billing_address_label: + type: string + pending_payment: + type: string + how_to_pay: + type: string + pay_for_order_help: + type: string + order_total: + type: string + cart_items: + type: string + sku: + type: string + quantity: + type: string + item_price: + type: string + item_total: + type: string + payment_method: + type: string + no_payment_taken_in_test_mode: + type: string + download_files: + type: string + preorder: + type: string + download_available_after_payment: + type: string + shipped_to: + type: string + shipping_discount: + type: string + thanks_for_your_order: + type: string + your_order_contains: + type: string + shipping_method: + type: string + shipping_to_address: + type: string + your_order_will_be_shipped_by: + type: string + total_cost: + type: string + items: + type: string + total: + type: string + price: + type: string + email_address: + type: string +examples: + order: + id: 1 + customer_message: Order custom message + customer_id: 11 + date_placed: + formatted: 11th Feb 2021 + value: 1613060604 + account_order_status_url: #url + shipping: + methods: + address: + email: 'test@gmail.com' + phone: +112233445566 + first_name: John + last_name: Wick + company: MyCompany + country: + city: + state: + zip: 1622 + address_lines: + custom_fields: + products: + - name: Test product name + quantity: 2 + sku: SF42 + address_lines: + address_id: 0 + options: + Size: XL + download_url: + thumbnail_url: /test.jpg + event: + name: + date: + value: 0 + formatted: + price: + value: 250.1 + formatted: 250.1 + total: + value: 250.1, + formatted: 250.1 + preorder: + is_preorder: false + message: + date: + value: 0 + formatted: + attribute_lines: + configurable_fields: + payment: + is_test: false + provider_name: PaymentMethod + offline_payment_message: + gateway_amount: + formatted: + value: 0 + billing: + is_managed_by_amazon: false + address: + email: 'test@gmail.com' + phone: +112233445566 + first_name: John + last_name: Wick + company: MyCompany + country: + city: + state: + zip: 1622 + address_lines: + custom_fields: + total_rows: + - label: Total, + price: + value: 250.1, + formatted: 250.1 + shipping_discounts: + total_cost: + formatted: 100.0$, + value: 100 + meta: + mandate_url: + shipping_addresses_num: 1 + show_immediate_download: false + store: + name: My Dev Store 97434969 + domain_name: 'my-dev-store-97434969.store.bcdev' + logo: + title: [= My Dev Store 97434969 =] + name: 'avatar-2020_1612860757__16350.jpeg' + url: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96/product_images/avatar-2020_1612860757__16350.jpeg' + ssl_path: 'https://my-dev-store-97434969.store.bcdev' + cdn_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96' + image_directory: product_images + img_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/r08d84bb67d250c7624502ed76d8e0bafb1a5cacf/g-themes/ClassicNext/images' + path_normal: 'https://my-dev-store-97434969.store.bcdev' + path: 'https://my-dev-store-97434969.store.bcdev' + address: '123 Fake St, Dallas, TX 75225' + language: + code: en + direction: ltr + customer: + first_name: John, + full_name: John Jr + email: 'john.f@example.com' + misc: + year: 2021 + translations: + en: + comment_label: Order Instructions/Comments + order_id_line: Your order ID is <strong>#{{id}}</strong>. + view_summary: A summary of your order is shown below. To view the status of your order <a href='link'>click here</a>. + sepa: 'SEPA Direct Debit Mandate' + shipment_to_multiple_addresses: (Order will be shipped to multiple addresses) + shipping_immediate_download: Immediate download after completion of payment. + shipping_address_label: Shipping Address + immediate_download: Immediate Download + email: Email + billing_address_managed_by_amazon: Managed by Amazon + billing_address_label: Billing Address + pending_payment: Your order requires payment before it can be finalized. Details on how to pay are shown below. + how_to_pay: Your order requires payment before it can be finalized. Details on how to pay are shown below. + pay_for_order_help: Once you've provided payment your order will be completed. + order_total: The outstanding balance of your order is amount + cart_items: Cart Items + sku: SKU + quantity: Qty + item_price: Item Price + item_total: Item Total + payment_method: Payment Method + no_payment_taken_in_test_mode: '<b>Please Note</b>: No money was taken for this order, because the payment provider is in test mode.' + download_files: Download Files + preorder: This product is available for pre-order only + download_available_after_payment: Items available for immediate download after completion of payment + shipped_to: Items shipped to address + shipping_discount: price off using code Coupon Code + thanks_for_your_order: Thanks for Your Order + your_order_contains: Your Order Contains... + shipping_method: Shipping Method + shipping_to_address: Shipping to Address + your_order_will_be_shipped_by: Your Order Will Be Shipped By... + total_cost: Total Cost + items: Items + total: Total + price: Price + email_address: Email Address diff --git a/models/email_templates/combined/order_message_notification.yml b/models/email_templates/combined/order_message_notification.yml new file mode 100644 index 000000000..9c9c987af --- /dev/null +++ b/models/email_templates/combined/order_message_notification.yml @@ -0,0 +1,123 @@ +title: Order Notification Email Template +description: Order notification email triggers when a retailer or store admin adds a message to an order. +type: object +properties: + notification: + type: object + properties: + message: + type: string + link: + type: string + subject: + type: string + store: + type: object + properties: + name: + type: string + domain_name: + type: string + logo: + type: object + properties: + title: + type: string + name: + type: string + url: + type: string + ssl_path: + type: string + cdn_path: + type: string + image_directory: + type: string + img_path: + type: string + path_normal: + type: string + description: 'Path to the store (i.e., domain + protocol)' + path: + type: string + address: + type: string + language: + type: object + properties: + code: + type: string + direction: + type: string + description: 'Left to right or right to left, depending on the language' + customer: + type: object + properties: + first_name: + type: string + full_name: + type: string + email: + type: string + group: + type: array + items: + type: object + properties: + name: + type: string + misc: + type: object + properties: + year: + type: integer + translations: + type: object + properties: + en: + type: object + properties: + title: + type: string + hello: + type: string + message: + type: string + reply: + type: string + go_shopping: + type: string +example: + notification: + message: Message from the retailer + link: 'https://my-dev-store-97434969.store.bcdev/account.php?action=inbox' + store: + name: My Dev Store 97434969 + domain_name: my-dev-store-97434969.store.bcdev + logo: + title: [= My Dev Store 97434969 =] + name: avatar-2020_1612860757__16350.jpeg + url: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96/product_images/avatar-2020_1612860757__16350.jpeg' + ssl_path: 'https://my-dev-store-97434969.store.bcdev' + cdn_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96' + image_directory: product_images + img_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/r08d84bb67d250c7624502ed76d8e0bafb1a5cacf/g-themes/ClassicNext/images' + path_normal: 'https://my-dev-store-97434969.store.bcdev' + path: 'https://my-dev-store-97434969.store.bcdev' + address: '123 Fake St, Dallas, TX 75225' + language: + code: en + direction: ltr + customer: + first_name: John + full_name: John Jr + email: 'john.f@example.com' + misc: + year: 2021 + translations: + en: + title: New Reply to your Order Message + hello: Hello {{name}}. + message: '{{name}} has sent you a message about your order.' + reply: Reply + go_shopping: Go shopping diff --git a/models/email_templates/combined/passwordless_login_email.yml b/models/email_templates/combined/passwordless_login_email.yml new file mode 100644 index 000000000..30db28ba8 --- /dev/null +++ b/models/email_templates/combined/passwordless_login_email.yml @@ -0,0 +1,120 @@ +title: Sign in Link Request Email Template +description: Sign-in request email triggers when an existing customer requests passwordless login while checking out. +type: object +properties: + passwordless_login: + type: object + properties: + link: + type: string + store: + type: object + properties: + name: + type: string + domain_name: + type: string + logo: + type: object + properties: + title: + type: string + name: + type: string + url: + type: string + ssl_path: + type: string + cdn_path: + type: string + image_directory: + type: string + img_path: + type: string + path_normal: + type: string + description: 'Path to the store (i.e., domain + protocol)' + path: + type: string + address: + type: string + language: + type: object + properties: + code: + type: string + direction: + type: string + description: 'Left to right or right to left, depending on the language' + customer: + type: object + properties: + first_name: + type: string + full_name: + type: string + email: + type: string + group: + type: array + items: + type: object + properties: + name: + type: string + misc: + type: object + properties: + year: + type: integer + translations: + type: object + properties: + en: + type: object + properties: + title: + type: string + message: + type: string + alternatively: + type: string + login_request: + type: string + secure: + type: string + go_shopping: + type: string +example: + passwordless_login: '"link": "#sign-in-link"' + store: + name: My Dev Store 97434969 + domain_name: 'my-dev-store-97434969.store.bcdev' + logo: + title: [= My Dev Store 97434969 =] + name: avatar-2020_1612860757__16350.jpeg + url: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96/product_images/avatar-2020_1612860757__16350.jpeg' + ssl_path: 'https://my-dev-store-97434969.store.bcdev' + cdn_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96' + image_directory: product_images + img_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/r08d84bb67d250c7624502ed76d8e0bafb1a5cacf/g-themes/ClassicNext/images' + path_normal: 'https://my-dev-store-97434969.store.bcdev' + path: 'https://my-dev-store-97434969.store.bcdev' + address: '123 Fake St, Dallas, TX 75225' + language: + code: en + direction: ltr + customer: + first_name: John + full_name: John Jr + email: 'john.f@example.com' + misc: + year: 2021 + translations: + en: + title: Please click the link below to sign in to your account with {{name}} + message: 'You have requested a sign-in link. Please <a href=\ {link}\ >click here to sign in</a> and continue.' + alternatively: 'Alternatively, paste the following link in your browser:' + login_request: This login is for {{name}} if you did not request this link, please ignore this email. + secure: Your account is still secure. + go_shopping: Go shopping diff --git a/models/email_templates/combined/product_review_email.yml b/models/email_templates/combined/product_review_email.yml new file mode 100644 index 000000000..ad5eea723 --- /dev/null +++ b/models/email_templates/combined/product_review_email.yml @@ -0,0 +1,143 @@ +title: Product Review Email Template +description: Product review request email triggers after a customer purchases a product. +type: object +properties: + review: + type: object + properties: + products: + type: array + items: + type: object + properties: + name: + type: string + sku: + type: string + link: + type: string + price: + type: string + thumbnail: + type: string + unsubscribe_link: + type: string + store: + type: object + properties: + name: + type: string + domain_name: + type: string + logo: + type: object + properties: + title: + type: string + name: + type: string + url: + type: string + ssl_path: + type: string + cdn_path: + type: string + image_directory: + type: string + img_path: + type: string + path_normal: + type: string + description: 'Path to the store (i.e., domain + protocol)' + path: + type: string + address: + type: string + language: + type: object + properties: + code: + type: string + direction: + type: string + description: 'Left to right or right to left, depending on the language' + customer: + type: object + properties: + first_name: + type: string + full_name: + type: string + email: + type: string + group: + type: array + items: + type: object + properties: + name: + type: string + misc: + type: object + properties: + year: + type: integer + translations: + type: object + properties: + en: + type: object + properties: + title: + type: string + hello: + type: string + message: + type: string + instruction: + type: string + review_text: + type: string + thanks: + type: string + go_shopping: + type: string +examples: + review: + products: + - name: Name of Product + sku: FA44 + link: '#review-link' + unsubscribe_link: '#unsubscribe-link' + store: + name: My Dev Store 97434969 + domain_name: my-dev-store-97434969.store.bcdev + logo: + title: [= My Dev Store 97434969 =] + name: avatar-2020_1612860757__16350.jpeg + url: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96/product_images/avatar-2020_1612860757__16350.jpeg' + ssl_path: 'https://my-dev-store-97434969.store.bcdev' + cdn_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96' + image_directory: product_images + img_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/r08d84bb67d250c7624502ed76d8e0bafb1a5cacf/g-themes/ClassicNext/images' + path_normal: 'https://my-dev-store-97434969.store.bcdev' + path: 'https://my-dev-store-97434969.store.bcdev' + address: '123 Fake St, Dallas, TX 75225' + language: + code: en + direction: ltr + customer: + first_name: John + full_name: John Jr + email: 'john.f@example.com' + misc: + year: 2021 + translations: + en: + title: Review products you've recently purchased + hello: Hello {{name}}, + message: Thanks for your recent order with us!, + instruction: If you have a few minutes, we'd like to invite you to review the products you ordered. Just click on the link below to write a review and share your opinion with other shoppers. + review_text: Review product + thanks: Thanks in advance for taking the time to review the products you purchased! + go_shopping: Go shopping diff --git a/models/email_templates/combined/return_confirmation_email.yml b/models/email_templates/combined/return_confirmation_email.yml new file mode 100644 index 000000000..108a0977b --- /dev/null +++ b/models/email_templates/combined/return_confirmation_email.yml @@ -0,0 +1,163 @@ +title: Return Requested Email Template +description: 'Return requested email triggers after a customer’s return is approved.' +type: object +properties: + return: + type: object + properties: + return_id: + type: string + reason: + type: string + action: + type: string + comments: + type: string + products: + type: array + items: + type: object + properties: + name: + type: string + quantity: + type: integer + price: + type: string + sku: + type: string + thumbnail: + type: string + order: + type: object + properties: + id: + type: integer + store: + type: object + properties: + name: + type: string + domain_name: + type: string + logo: + type: object + properties: + title: + type: string + name: + type: string + url: + type: string + ssl_path: + type: string + cdn_path: + type: string + image_directory: + type: string + img_path: + type: string + path_normal: + type: string + description: 'Path to the store (i.e., domain + protocol)' + path: + type: string + address: + type: string + language: + type: object + properties: + code: + type: string + direction: + type: string + description: 'Left to right or right to left, depending on the language' + customer: + type: object + properties: + first_name: + type: string + full_name: + type: string + email: + type: string + group: + type: array + items: + type: object + properties: + name: + type: string + misc: + type: object + properties: + year: + type: integer + translations: + type: object + properties: + en: + type: object + properties: + confirmation: + type: string + summary: + type: string + clickHere: + type: string + reason: + type: string + action: + type: string + comments: + type: string + contains: + type: string + items: + type: string + quantity: + type: string +example: + return: + return_id: 123 + reason: reason of return + action: action + comments: sample comment + order_id: 321 + products: + - name: Shower Gel + quantity: 3 + store: + name: My Dev Store 97434969 + domain_name: 'my-dev-store-97434969.store.bcdev' + logo: + title: '[= My Dev Store 97434969 =]' + name: avatar-2020_1612860757__16350.jpeg + url: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96/product_images/avatar-2020_1612860757__16350.jpeg' + ssl_path: 'https://my-dev-store-97434969.store.bcdev' + cdn_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96' + image_directory: product_images + img_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/r08d84bb67d250c7624502ed76d8e0bafb1a5cacf/g-themes/ClassicNext/images' + path_normal: 'https://my-dev-store-97434969.store.bcdev' + path: 'https://my-dev-store-97434969.store.bcdev' + address: '123 Fake St, Dallas, TX 75225' + language: + code: en + direction: ltr + customer: + first_name: John + full_name: John Jr + email: 'john.f@example.com' + misc: + year: 2021 + translations: + en: + confirmation: Confirmation for Return Request for Order ID + summary: A summary of your return is shown below. To view the status of this return + clickHere: click here + reason: Return Reason + action: Return Action + comments: Your Comments + contains: Your Return Request Contains the Following Items... + items: Return Items + quantity: Qty diff --git a/models/email_templates/combined/return_status_change_email.yml b/models/email_templates/combined/return_status_change_email.yml new file mode 100644 index 000000000..7b712671b --- /dev/null +++ b/models/email_templates/combined/return_status_change_email.yml @@ -0,0 +1,201 @@ +description: Return status change email triggers after a customer returnʼs status has changed. +type: object +title: Return Status Change Email Template +properties: + return: + type: object + properties: + id: + type: integer + reason: + type: string + action: + type: string + comments: + type: string + product: + type: object + properties: + name: + type: string + quantity: + type: integer + price: + type: string + sku: + type: string + thumbnail: + type: string + status: + type: object + properties: + value: + type: integer + formatted: + type: string + store_credit: + type: object + properties: + value: + type: float + formatted: + type: string + link: + type: string + instructions: + type: string + order: + type: object + properties: + id: + type: integer + store: + type: object + properties: + name: + type: string + domain_name: + type: string + logo: + type: object + properties: + title: + type: string + name: + type: string + url: + type: string + ssl_path: + type: string + cdn_path: + type: string + image_directory: + type: string + img_path: + type: string + path_normal: + type: string + description: 'Path to the store (i.e., domain + protocol)' + path: + type: string + address: + type: string + language: + type: object + properties: + code: + type: string + direction: + type: string + description: 'Left to right or right to left, depending on the language' + customer: + type: object + properties: + first_name: + type: string + full_name: + type: string + email: + type: string + group: + type: array + items: + type: object + properties: + name: + type: string + misc: + type: object + properties: + year: + type: integer + translations: + type: object + properties: + en: + type: object + properties: + title: + type: string + hello: + type: string + message: + type: string + received_credit: + type: string + details_title: + type: string + return_reason: + type: string + return_action: + type: string + return_comments: + type: string + check_status: + type: string + products_title: + type: string + quantity: + type: string + instructions_title: + type: string + go_shopping: + type: string +example: + return: + id: 1 + reason: reason of return + action: action + comments: sample comment + product: + name: ProductName + quantity: 2 + thumbnail_url: '' + status: + value: 1 + formatted: Pending + store_credit: + value: 10.1 + formatted: '$10.1 USD' + link: 'https://my-dev-store-97434969.store.bcdev/account.php?action=view_returns' + instructions: + order: + id: 1 + store: + name: My Dev Store 97434969 + domain_name: my-dev-store-97434969.store.bcdev + logo: + title: '[= My Dev Store 97434969 =]' + name: avatar-2020_1612860757__16350.jpeg + url: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96/product_images/avatar-2020_1612860757__16350.jpeg' + ssl_path: 'https://my-dev-store-97434969.store.bcdev' + cdn_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/store/f1kr2akw96' + image_directory: product_images + img_path: 'https://valeryderived-cloud-dev-vm.store.bcdev/r08d84bb67d250c7624502ed76d8e0bafb1a5cacf/g-themes/ClassicNext/images' + path_normal: 'https://my-dev-store-97434969.store.bcdev' + path: 'https://my-dev-store-97434969.store.bcdev' + address: '123 Fake St, Dallas, TX 75225' + language: + code: en + direction: ltr + customer: + first_name: John + full_name: John Jr + email: 'john.f@example.com' + misc: + year: 2021 + translations: + en: + title: 'Return request status changed' + hello: 'Hello {{name}}' + message: 'The status of your return request for order #{{id}} has changed to <strong>{{status}}</strong>.' + received_credit: 'You have received a store credit of {{credits}} To use it simply place your order and you will be able to choose store credit as the payment method when it comes time to pay for your order.' + details_title: Return details + return_reason: 'Return reason:' + return_action: 'Return action:' + return_comments: 'Your comments:' + check_status: Check return status + products_title: Return items + quantity: 'Qty:' + instructions_title: 'Return Instructions:' + go_shopping: Go shopping diff --git a/models/webhooks/_all.yml b/models/webhooks/_all.yml index bc9c81b82..47b246ed7 100644 --- a/models/webhooks/_all.yml +++ b/models/webhooks/_all.yml @@ -3,217 +3,412 @@ title: 'Webhook Events' description: properties: store/app/uninstalled: - description: Occurs when a client store is cancelled and uninstalled from the platform. + description: Fires when a client store is cancelled and uninstalled from the platform. type: object allOf: - $ref: ./store_app_uninstalled.yml + store/brand/metafield/created: + description: Fires when a new brand metafield is created. + type: object + allOf: + - $ref: ./store_brand_metafield_created.yml + store/brand/metafield/deleted: + description: Fires when a brand metafield is deleted. + type: object + allOf: + - $ref: ./store_brand_metafield_deleted.yml + store/brand/metafield/updated: + description: Fires when a brand metafield is modified. + type: object + allOf: + - $ref: ./store_brand_metafield_updated.yml store/cart/abandoned: - description: This webhook will fire once after a cart is abandoned. A cart is considered abandoned if no changes have been made for at least one hour after the last modified property. This hook is available for all store plans, regardless of whether the Abandoned Cart Saver feature is enabled. + description: Fires when a cart is abandoned. A cart is considered abandoned when no changes have been made to its properties or contents for one hour. This webhook is available for all store plans, regardless of whether the Abandoned Cart Saver feature is enabled. type: object allOf: - $ref: ./store_cart_abandoned.yml store/cart/converted: - description: This hook fires when a cart is converted into an order, which is typically after the payment step of checkout on the storefront. At this point, the cart is no longer accessible and has been deleted. This hook returns both the cart ID and order ID for correlation purposes. + description: Fires when a cart is converted into an order, which typically follows the payment step of checkout. At this point, the cart is no longer accessible and has been deleted. This webhook returns both the cart ID and the order ID for correlation purposes. type: object allOf: - $ref: ./store_cart_converted.yml store/cart/couponApplied: - description: This webhook will fire whenever a new coupon code is applied to a cart. It will include the ID of the coupon code. + description: Fires when a new coupon code is applied to a cart. The payload includes the ID of the coupon code. type: object allOf: - $ref: ./store_cart_couponApplied.yml store/cart/created: - description: This webhook will fire whenever a new cart is created, either via a storefront shopper adding their first item to the cart, or when a new cart is created via an API consumer. If it is from the storefront, then it fires when the first product is added to a new session.(The cart did not exist before). For the API it means a POST to /carts, (V3 and Storefront API). The store/cart/updated hook will also fire. + description: |- + Fires when a new cart is created, which happens with the following two events: + + * A storefront shopper adds the first item to their cart + * A new cart is created using any of the APIs that can create carts + + The store/cart/updated webhook fires simultaneously with store/cart/created. type: object allOf: - $ref: ./store_cart_created.yml store/cart/deleted: - description: This webhook will fire whenever a cart is deleted. This will occur either when all items have been removed from a cart and it is auto-deleted, or when the cart is explicitly removed via a DELETE request by an API consumer. This ends the lifecycle of the cart. The store/cart/updated webhook will also fire when the last item is removed. + description: |- + Fires when a cart is deleted. This ends the lifecycle of the cart. Events include the following: + + * When a storefront shopper or API call removes all items from the cart + * When the cart is explicitly removed by API using a DELETE request + + The store/cart/updated webhook fires simultaneously with store/cart/deleted. type: object allOf: - $ref: ./store_cart_deleted.yml store/cart/lineItem/created: - description: When a new item is added to the cart + description: Fires when a new item is added to a cart. type: object allOf: - $ref: ./store_cart_lineItem_created.yml store/cart/lineItem/deleted: - description: When an item is deleted from the cart + description: Fires when an item is deleted from a cart. type: object allOf: - $ref: ./store_cart_lineItem_deleted.yml store/cart/lineItem/updated: - description: When an item’s quantity has changed or the product options change. + description: Fires when a line item’s quantity or product options change. type: object allOf: - $ref: ./store_cart_lineItem_updated.yml + store/cart/metafield/created: + description: Fires when a new cart metafield is created. + type: object + allOf: + - $ref: ./store_cart_metafield_created.yml + store/cart/metafield/deleted: + description: Fires when a cart metafield is deleted. + type: object + allOf: + - $ref: ./store_cart_metafield_deleted.yml + store/cart/metafield/updated: + description: Fires when a cart metafield is modified through the changes in its line items. + type: object + allOf: + - $ref: ./store_cart_metafield_updated.yml store/cart/updated: - description: his webhook is fired whenever a cart is modified through the changes in its line items. Eg. when a new item is added to a cart or an existing item’s quantity is updated. This hook also fires when the email is changed during guest checkout or when an existing item is deleted. The payload will include the ID of the cart being updated. This webhook also fires along with the cart created hook, because the first product being added to an empty cart triggers an update. + description: |- + Fires when a cart is modified, including in the following cases: + + * When a new item is added to a cart + * When an existing item’s quantity is updated + * When an existing item is deleted + * When the email is changed during guest checkout + * When the store/cart/created webhook fires + * When the store/cart/deleted webhook fires + + The payload includes the ID of the cart being updated. type: object allOf: - $ref: ./store_cart_updated.yml store/category/created: - description: Category is created + description: Fires when a new category is created. type: object allOf: - $ref: ./store_category_created.yml store/category/deleted: - description: Category is deleted + description: Fires when a category is deleted. type: object allOf: - $ref: ./store_category_deleted.yml store/category/updated: - description: Category is updated + description: Fires when a category is updated. type: object allOf: - $ref: ./store_category_updated.yml + store/category/metafield/created: + description: Fires when a new cart metafield is created. + type: object + allOf: + - $ref: ./store_category_metafield_created.yml + store/category/metafield/deleted: + description: Fires when a cart metafield is deleted. + type: object + allOf: + - $ref: ./store_category_metafield_deleted.yml + store/category/metafield/updated: + description: Fires when a cart metafield is modified through the changes in its line items. + type: object + allOf: + - $ref: ./store_category_metafield_updated.yml + store/channel/metafield/created: + description: Fires when a metafield is created per a specified channel. + type: object + allOf: + - $ref: ./store_channel_metafield_created.yml + store/channel/metafield/deleted: + description: Fires when a metafield is deleted per a specified channel. + type: object + allOf: + - $ref: ./store_channel_metafield_deleted.yml + store/channel/metafield/updated: + description: Fires when a cart metafield is modified through the changes in its line items. + type: object + allOf: + - $ref: ./store_channel_metafield_updated.yml store/customer/address/created: - description: Customer address is created + description: Fires when a customer address is created. type: object allOf: - $ref: ./store_customer_address_created.yml store/customer/address/deleted: - description: Customer address is deleted + description: Fires when a customer address is deleted. type: object allOf: - $ref: ./store_customer_address_deleted.yml store/customer/address/updated: - description: Customer address is updated + description: Fires when a customer address is updated. type: object allOf: - $ref: ./store_customer_address_updated.yml store/customer/created: - description: A new customer is created + description: Fires when a new customer is created. type: object allOf: - $ref: ./store_customer_created.yml store/customer/deleted: - description: Customer is deleted + description: Fires when a customer is deleted. type: object allOf: - $ref: ./store_customer_deleted.yml store/customer/payment/instrument/default/updated: - description: Customer default payment instrument is updated + description: Fires when a customerʼs default payment instrument is updated. type: object allOf: - $ref: ./store_customer_payment_instrument_default_updated.yml store/customer/updated: - description: Customer is updated. Does not currently track changes to the customer address. + description: Fires when a customer is updated. It does not currently track changes to the customer address. <br /><br />Tracks changes to customer attributes only if you make the changes through the control panel. This change triggers the same event `type` and payload as updating a customer; the payload does not include customer attributes. + type: object allOf: - $ref: ./store_customer_updated.yml store/information/updated: - description: Occurs when changes are made to store settings. For a full list of fields that can trigger this event, see Store information updated events below + description: Fires when changes are made to store settings. For a full list of fields that can trigger this event, see the store information updated events that follow. type: object allOf: - $ref: ./store_information_updated.yml + store/inventory/location/created: + description: Fires when a location is created. + type: object + allOf: + - $ref: ./store_inventory_location_created.yml + store/inventory/location/updated: + description: Fires when a location is updated. + type: object + allOf: + - $ref: ./store_inventory_location_updated.yml + store/inventory/location/metafield/created: + description: Fires when a new inventory location metafield is created. + type: object + allOf: + - $ref: ./store_inventory_location_metafield_created.yml + store/inventory/location/metafield/deleted: + description: Fires when an inventory location metafield is deleted. + type: object + allOf: + - $ref: ./store_inventory_location_metafield_deleted.yml + store/inventory/location/metafield/updated: + description: Fires when an existing inventory location metafield is updated. + type: object + allOf: + - $ref: ./store_inventory_location_metafield_updated.yml + store/metafield/created: + description: Fires whenever a new metafield on any object is created. + type: object + allOf: + - $ref: ./store_metafield_created.yml + store/metafield/deleted: + description: Fires whenever a metafield is deleted. + type: object + allOf: + - $ref: ./store_metafield_deleted.yml + store/metafield/updated: + description: Fires when an already created metafield is updated. Any changes to an existing metafield on any object (such as inventory, carts, brands, categories, channels, orders, ShipperHQ, etc.) will fire this webhook. + type: object + allOf: + - $ref: ./store_metafield_updated.yml store/order/archived: - description: Order is archived + description: Fires when an order is archived. type: object allOf: - $ref: ./store_order_archived.yml store/order/created: - description: Fires if an order is created using the control panel, an app or via the API + description: Fires when an order is created either in the control panel or by API. type: object allOf: - $ref: ./store_order_created.yml store/order/message/created: - description: Order message is created by customer or in control panel + description: Fires when an order message is created by a customer or using the control panel. type: object allOf: - $ref: ./store_order_message_created.yml + store/order/metafield/created: + description: Fires if an order metafield is created using the control panel, an app, or the API. + type: object + allOf: + - $ref: ./store_order_metafield_created.yml + store/order/metafield/deleted: + description: Fires when an order metafield is deleted. + type: object + allOf: + - $ref: ./store_order_metafield_deleted.yml + store/order/metafield/updated: + description: Fires when an existing order metafield is updated. Any changes to an existing order metafield will fire this webhook. + type: object + allOf: + - $ref: ./store_order_metafield_updated.yml store/order/refund/created: - description: A refund has been submitted against an order + description: Fires when a refund is submitted against an order. type: object allOf: - $ref: ./store_order_refund_created.yml store/order/statusUpdated: - description: This will only fire if the order status has changed. Such as Pending to Awaiting Payment + description: Fires when the order status has changed, such as from Pending to Awaiting Payment. type: object allOf: - $ref: ./store_order_statusUpdated.yml + store/order/transaction/created: + description: Fires when an order transaction is created. + type: object + allOf: + - $ref: ./store_order_transaction_created.yml + store/order/transaction/updated: + description: Fires when an order transaction is changed. + type: object + allOf: + - $ref: ./store_order_transaction_updated.yml store/order/updated: - description: Fires when an already created order is updated. Any changes to an existing order will fire this webhook. Updates can include changing the status, updating a coupon or changing an address. + description: Fires when an already created order is updated. Any change to an existing order fires this webhook. Updates can include changing the status, updating a coupon, or changing an address. type: object allOf: - $ref: ./store_order_updated.yml store/product/created: - description: A new product is created + description: Fires when new product is created. type: object allOf: - $ref: ./store_product_created.yml store/product/deleted: - description: Product is deleted + description: Fires when a product is deleted. type: object allOf: - $ref: ./store_product_deleted.yml store/product/inventory/order/updated: - description: Fires if a product’s inventory is decremented or incremented, including when an order is placed. Webhook responds to inventory updates made using the control panel, CSV import, API or an app. + description: |- + Fires when _base product_ inventory levels change in response to the order-related events configured in [Inventory settings](/docs/rest-management/settings/inventory#get-inventory-settings). For example, stock levels can change when you either place or complete/ship an order. Stock levels can also change when you refund or cancel an order. Global settings apply when inventory changes through a [manual order](https://support.bigcommerce.com/s/article/Creating-a-Manual-Order?language=en_US). The settings for a channel apply when inventory changes through an order in a channel. + + The webhook always fires for products without variants. For products with variants, the webhook only fires when the product's inventory properties are configured to track by _product_. type: object allOf: - $ref: ./store_product_inventory_order_updated.yml store/product/inventory/updated: - description: Product inventory is updated. + description: |- + Fires when inventory levels change for a _base product_. For products without variants, the webhook fires regardless of how you track inventory. + + For products with variants, the webhook only fires when the product's inventory properties are configured to track by _product_ and the _product-level_ inventory changes. + + Inventory updates made in the control panel and by API trigger the webhook. This includes changes made by apps. In the control panel, you can bulk import inventory updates or make inventory updates to single products on the **Products > View** page. type: object allOf: - $ref: ./store_product_inventory_updated.yml + store/product/metafield/created: + description: Fires when a new product metafield is created. + type: object + allOf: + - $ref: ./store_product_metafield_created.yml + store/product/metafield/deleted: + description: Fires when a product metafield is deleted. + type: object + allOf: + - $ref: ./store_product_metafield_deleted.yml + store/product/metafield/updated: + description: Fires when product metafield details are edited. + type: object + allOf: + - $ref: ./store_product_metafield_updated.yml store/product/updated: - description: Occurs when product details are edited. For a full list of product fields that trigger an updated event, see Product updated events below + description: Fires when product details are edited. For a full list of product fields that trigger an updated event, see the product updated events that follow. type: object allOf: - $ref: ./store_product_updated.yml + store/product/variant/metafield/created: + description: Fires when a new product variant metafield is created. + type: object + allOf: + - $ref: ./store_variant_metafield_created.yml + store/product/variant/metafield/deleted: + description: Fires when a product variant metafield is deleted.. + type: object + allOf: + - $ref: ./store_variant_metafield_deleted.yml + store/product/variant/metafield/updated: + description: Fires when product variant metafield details are edited. + type: object + allOf: + - $ref: ./store_variant_metafield_updated.yml store/shipment/created: - description: Shipment is created + description: Fires when a shipment is created. type: object allOf: - $ref: ./store_shipment_created.yml store/shipment/deleted: - description: Shipment is deleted + description: Fires when a shipment is deleted. type: object allOf: - $ref: ./store_shipment_deleted.yml store/shipment/updated: - description: Shipment is updated + description: Fires when a shipment is updated. type: object allOf: - $ref: ./store_shipment_updated.yml store/sku/created: - description: A new sku is created + description: Fires when a new SKU is created. type: object allOf: - $ref: ./store_sku_created.yml store/sku/deleted: - description: SKU is deleted + description: Fires when a SKU is deleted. type: object allOf: - $ref: ./store_sku_deleted.yml store/sku/inventory/order/updated: - description: This will fire when the inventory is updated via API, the control panel, when an order is placed and when an order is refunded and the inventory is returned to stock. This hook will fire based on a store’s Inventory settings. + description: |- + Fires when _variant_ inventory levels change in response to the order-related events configured in [Inventory settings](/docs/rest-management/settings/inventory#get-inventory-settings). For example, stock levels can change when you either place or complete/ship an order. Stock levels can also change when you refund or cancel an order. Global settings apply when inventory changes through a [manual order](https://support.bigcommerce.com/s/article/Creating-a-Manual-Order?language=en_US). The settings for a channel apply when inventory changes through an order in a channel. + + The webhook does not fire for products without variants. For products with variants, the webhook only fires when the product's inventory properties are configured to track by _variant_. type: object allOf: - $ref: ./store_sku_inventory_order_updated.yml store/sku/inventory/updated: - description: SKU is updated + description: |- + Fires when inventory levels change for a _variant_. This webhook does not fire for products without variants. + + For products with variants, the webhook only fires when the product's inventory properties are configured to track by _variant_ and the _variant-level_ inventory changes. + + Inventory updates made in the control panel and by API trigger the webhook. This includes changes made by apps. In the control panel, you can bulk import inventory updates or make inventory updates to single products on the **Products > View** page. type: object allOf: - $ref: ./store_sku_inventory_updated.yml store/sku/updated: - description: SKU is updated + description: Fires when a SKU is updated. type: object allOf: - $ref: ./store_sku_updated.yml store/subscriber/created: - description: Subscriber is created + description: Fires when a subscriber is created. type: object allOf: - $ref: ./store_subscriber_created.yml store/subscriber/deleted: - description: Subscriber is deleted + description: Fires when a subscriber is deleted. type: object allOf: - $ref: ./store_subscriber_deleted.yml store/subscriber/updated: - description: Subscriber is updated + description: Fires when a subscriber is updated. type: object allOf: - - $ref: ./store_subscriber_updated.yml \ No newline at end of file + - $ref: ./store_subscriber_updated.yml + diff --git a/models/webhooks/data/store_metafield_created.json b/models/webhooks/data/store_metafield_created.json new file mode 100644 index 000000000..8b1378917 --- /dev/null +++ b/models/webhooks/data/store_metafield_created.json @@ -0,0 +1 @@ + diff --git a/models/webhooks/store_app_uninstalled.yml b/models/webhooks/store_app_uninstalled.yml index 8b6caefce..7a6801b6d 100644 --- a/models/webhooks/store_app_uninstalled.yml +++ b/models/webhooks/store_app_uninstalled.yml @@ -1,7 +1,7 @@ type: object properties: store/app/uninstalled: - description: Occurs when a client store is cancelled and uninstalled from the platform. + description: Fires when a client store is cancelled and uninstalled from the platform. type: object properties: scope: diff --git a/models/webhooks/store_brand_metafield_created.yml b/models/webhooks/store_brand_metafield_created.yml new file mode 100644 index 000000000..ee7053d71 --- /dev/null +++ b/models/webhooks/store_brand_metafield_created.yml @@ -0,0 +1,23 @@ +type: object +properties: + store/brand/metafield/created: + description: Fires when a new metafield on any object is created. + type: object + properties: + scope: + type: string + store_id: + type: string + data: + type: object + properties: + metafield_id: + type: integer + resource_id: + type: string + hash: + type: string + created_at: + type: integer + producer: + type: string diff --git a/models/webhooks/store_brand_metafield_deleted.yml b/models/webhooks/store_brand_metafield_deleted.yml new file mode 100644 index 000000000..c3ef54bbd --- /dev/null +++ b/models/webhooks/store_brand_metafield_deleted.yml @@ -0,0 +1,23 @@ +type: object +properties: + store/brand/metafield/deleted: + description: Fires when a brand metafield is deleted. + type: object + properties: + scope: + type: string + store_id: + type: string + data: + type: object + properties: + metafield_id: + type: integer + resource_id: + type: string + hash: + type: string + created_at: + type: integer + producer: + type: string diff --git a/models/webhooks/store_brand_metafield_updated.yml b/models/webhooks/store_brand_metafield_updated.yml new file mode 100644 index 000000000..d09441d1b --- /dev/null +++ b/models/webhooks/store_brand_metafield_updated.yml @@ -0,0 +1,23 @@ +type: object +properties: + store/brand/metafield/updated: + description: Fires when a brand metafield is modified. + type: object + properties: + scope: + type: string + store_id: + type: string + data: + type: object + properties: + metafield_id: + type: integer + resource_id: + type: string + hash: + type: string + created_at: + type: integer + producer: + type: string diff --git a/models/webhooks/store_cart_abandoned.yml b/models/webhooks/store_cart_abandoned.yml index 592f11c3c..2e070c98b 100644 --- a/models/webhooks/store_cart_abandoned.yml +++ b/models/webhooks/store_cart_abandoned.yml @@ -1,7 +1,7 @@ type: object properties: store/cart/abandoned: - description: This webhook will fire once after a cart is abandoned. A cart is considered abandoned if no changes have been made for at least one hour after the last modified property. This hook is available for all store plans, regardless of whether the Abandoned Cart Saver feature is enabled. + description: Fires when a cart is abandoned. A cart is considered abandoned when no changes have been made to its properties or contents for one hour. This webhook is available for all store plans, regardless of whether the Abandoned Cart Saver feature is enabled. type: object properties: scope: diff --git a/models/webhooks/store_cart_converted.yml b/models/webhooks/store_cart_converted.yml index 4d899ccec..5539d7e1e 100644 --- a/models/webhooks/store_cart_converted.yml +++ b/models/webhooks/store_cart_converted.yml @@ -1,7 +1,7 @@ type: object properties: store/cart/converted: - description: This hook fires when a cart is converted into an order, which is typically after the payment step of checkout on the storefront. At this point, the cart is no longer accessible and has been deleted. This hook returns both the cart ID and order ID for correlation purposes. + description: Fires when a cart is converted into an order, which typically follows the payment step of checkout. At this point, the cart is no longer accessible and has been deleted. This webhook returns both the cart ID and the order ID for correlation purposes. type: object properties: scope: diff --git a/models/webhooks/store_cart_couponApplied.yml b/models/webhooks/store_cart_couponApplied.yml index 0ceda9be2..87b82ff15 100644 --- a/models/webhooks/store_cart_couponApplied.yml +++ b/models/webhooks/store_cart_couponApplied.yml @@ -1,7 +1,7 @@ type: object properties: store/cart/couponApplied: - description: This webhook will fire whenever a new coupon code is applied to a cart. It will include the ID of the coupon code. + description: Fires when a new coupon code is applied to a cart. The payload includes the ID of the coupon code. type: object properties: scope: diff --git a/models/webhooks/store_cart_created.yml b/models/webhooks/store_cart_created.yml index b60f95f90..a390e71a1 100644 --- a/models/webhooks/store_cart_created.yml +++ b/models/webhooks/store_cart_created.yml @@ -1,7 +1,13 @@ type: object properties: store/cart/created: - description: This webhook will fire whenever a new cart is created, either via a storefront shopper adding their first item to the cart, or when a new cart is created via an API consumer. If it is from the storefront, then it fires when the first product is added to a new session.(The cart did not exist before). For the API it means a POST to /carts, (V3 and Storefront API). The store/cart/updated hook will also fire. + description: |- + Fires when a new cart is created, which happens with the following two events: + + * A storefront shopper adds the first item to their cart + * A new cart is created using any of the APIs that can create carts + + The store/cart/updated webhook fires simultaneously with store/cart/created. type: object properties: scope: diff --git a/models/webhooks/store_cart_deleted.yml b/models/webhooks/store_cart_deleted.yml index c1980272b..a7548fcbd 100644 --- a/models/webhooks/store_cart_deleted.yml +++ b/models/webhooks/store_cart_deleted.yml @@ -1,7 +1,13 @@ type: object properties: store/cart/deleted: - description: This webhook will fire whenever a cart is deleted. This will occur either when all items have been removed from a cart and it is auto-deleted, or when the cart is explicitly removed via a DELETE request by an API consumer. This ends the lifecycle of the cart. The store/cart/updated webhook will also fire when the last item is removed. + description: |- + Fires when a cart is deleted. This ends the lifecycle of the cart. Events include the following: + + * When a storefront shopper or API call removes all items from the cart + * When the cart is explicitly removed by API using a DELETE request + + The store/cart/updated webhook fires simultaneously with store/cart/deleted. type: object properties: scope: diff --git a/models/webhooks/store_cart_lineItem_created.yml b/models/webhooks/store_cart_lineItem_created.yml index 44e0d4e84..9c6a4cf10 100644 --- a/models/webhooks/store_cart_lineItem_created.yml +++ b/models/webhooks/store_cart_lineItem_created.yml @@ -1,7 +1,7 @@ type: object properties: store/cart/lineItem/created: - description: When a new item is added to the cart + description: Fires when a new item is added to a cart. type: object properties: scope: diff --git a/models/webhooks/store_cart_lineItem_deleted.yml b/models/webhooks/store_cart_lineItem_deleted.yml index 53dfcfb26..50fd621bf 100644 --- a/models/webhooks/store_cart_lineItem_deleted.yml +++ b/models/webhooks/store_cart_lineItem_deleted.yml @@ -1,7 +1,7 @@ type: object properties: store/cart/lineItem/deleted: - description: When an item is deleted from the cart + description: Fires when an item is deleted from a cart. type: object properties: scope: diff --git a/models/webhooks/store_cart_lineItem_updated.yml b/models/webhooks/store_cart_lineItem_updated.yml index ad5caea2c..5035ced59 100644 --- a/models/webhooks/store_cart_lineItem_updated.yml +++ b/models/webhooks/store_cart_lineItem_updated.yml @@ -1,7 +1,7 @@ type: object properties: store/cart/lineItem/updated: - description: When an item’s quantity has changed or the product options change. + description: Fires when a line item’s quantity or product options change. type: object properties: scope: diff --git a/models/webhooks/store_cart_metafield_created.yml b/models/webhooks/store_cart_metafield_created.yml new file mode 100644 index 000000000..7bc684fe0 --- /dev/null +++ b/models/webhooks/store_cart_metafield_created.yml @@ -0,0 +1,23 @@ +type: object +properties: + store/cart/metafield/created: + description: Fires when a new cart metafield is created. + type: object + properties: + scope: + type: string + store_id: + type: string + data: + type: object + properties: + metafield_id: + type: integer + resource_id: + type: string + hash: + type: string + created_at: + type: integer + producer: + type: string diff --git a/models/webhooks/store_cart_metafield_deleted.yml b/models/webhooks/store_cart_metafield_deleted.yml new file mode 100644 index 000000000..1d8b095a4 --- /dev/null +++ b/models/webhooks/store_cart_metafield_deleted.yml @@ -0,0 +1,23 @@ +type: object +properties: + store/cart/metafield/deleted: + description: Fires when a cart metafield is deleted. + type: object + properties: + scope: + type: string + store_id: + type: string + data: + type: object + properties: + metafield_id: + type: integer + resource_id: + type: string + hash: + type: string + created_at: + type: integer + producer: + type: string diff --git a/models/webhooks/store_cart_metafield_updated.yml b/models/webhooks/store_cart_metafield_updated.yml new file mode 100644 index 000000000..609f9bf0f --- /dev/null +++ b/models/webhooks/store_cart_metafield_updated.yml @@ -0,0 +1,23 @@ +type: object +properties: + store/cart/metafield/updated: + description: Fires when a cart metafield is modified through the changes in its line items. + type: object + properties: + scope: + type: string + store_id: + type: string + data: + type: object + properties: + metafield_id: + type: integer + resource_id: + type: string + hash: + type: string + created_at: + type: integer + producer: + type: string diff --git a/models/webhooks/store_cart_updated.yml b/models/webhooks/store_cart_updated.yml index 2550c783e..ace0086f3 100644 --- a/models/webhooks/store_cart_updated.yml +++ b/models/webhooks/store_cart_updated.yml @@ -1,7 +1,17 @@ type: object properties: store/cart/updated: - description: his webhook is fired whenever a cart is modified through the changes in its line items. Eg. when a new item is added to a cart or an existing item’s quantity is updated. This hook also fires when the email is changed during guest checkout or when an existing item is deleted. The payload will include the ID of the cart being updated. This webhook also fires along with the cart created hook, because the first product being added to an empty cart triggers an update. + description: |- + Fires when a cart is modified, including in the following cases: + + * When a new item is added to a cart + * When an existing item’s quantity is updated + * When an existing item is deleted + * When the email is changed during guest checkout + * When the store/cart/created webhook fires + * When the store/cart/deleted webhook fires + + The payload includes the ID of the cart being updated. type: object properties: scope: diff --git a/models/webhooks/store_category_created.yml b/models/webhooks/store_category_created.yml index c72c55399..bb37cbb32 100644 --- a/models/webhooks/store_category_created.yml +++ b/models/webhooks/store_category_created.yml @@ -1,7 +1,7 @@ type: object properties: store/category/created: - description: Category is created + description: Fires when a category is created. type: object properties: scope: diff --git a/models/webhooks/store_category_deleted.yml b/models/webhooks/store_category_deleted.yml index e47569597..ad60a0ebc 100644 --- a/models/webhooks/store_category_deleted.yml +++ b/models/webhooks/store_category_deleted.yml @@ -1,7 +1,7 @@ type: object properties: store/category/deleted: - description: Category is deleted + description: Fires when a category is deleted type: object properties: scope: diff --git a/models/webhooks/store_category_metafield_created.yml b/models/webhooks/store_category_metafield_created.yml new file mode 100644 index 000000000..35b433979 --- /dev/null +++ b/models/webhooks/store_category_metafield_created.yml @@ -0,0 +1,23 @@ +type: object +properties: + store/category/metafield/created: + description: Fires if a category metafield is created. + type: object + properties: + scope: + type: string + store_id: + type: string + data: + type: object + properties: + metafield_id: + type: integer + resource_id: + type: string + hash: + type: string + created_at: + type: integer + producer: + type: string diff --git a/models/webhooks/store_category_metafield_deleted.yml b/models/webhooks/store_category_metafield_deleted.yml new file mode 100644 index 000000000..93cfc7b89 --- /dev/null +++ b/models/webhooks/store_category_metafield_deleted.yml @@ -0,0 +1,23 @@ +type: object +properties: + store/category/metafield/deleted: + description: Fires if a category metafield is deleted. + type: object + properties: + scope: + type: string + store_id: + type: string + data: + type: object + properties: + metafield_id: + type: integer + resource_id: + type: string + hash: + type: string + created_at: + type: integer + producer: + type: string diff --git a/models/webhooks/store_category_metafield_updated.yml b/models/webhooks/store_category_metafield_updated.yml new file mode 100644 index 000000000..af21c3f53 --- /dev/null +++ b/models/webhooks/store_category_metafield_updated.yml @@ -0,0 +1,23 @@ +type: object +properties: + store/category/metafield/updated: + description: Fires if a category metafield is updated. + type: object + properties: + scope: + type: string + store_id: + type: string + data: + type: object + properties: + metafield_id: + type: integer + resource_id: + type: string + hash: + type: string + created_at: + type: integer + producer: + type: string diff --git a/models/webhooks/store_category_updated.yml b/models/webhooks/store_category_updated.yml index bb16b06a8..e8b5c8a85 100644 --- a/models/webhooks/store_category_updated.yml +++ b/models/webhooks/store_category_updated.yml @@ -1,7 +1,7 @@ type: object properties: store/category/updated: - description: Category is updated + description: Fires when a category is updated type: object properties: scope: diff --git a/models/webhooks/store_channel_metafield_created.yml b/models/webhooks/store_channel_metafield_created.yml new file mode 100644 index 000000000..99f64bb5b --- /dev/null +++ b/models/webhooks/store_channel_metafield_created.yml @@ -0,0 +1,23 @@ +type: object +properties: + store/channel/metafield/created: + description: Fires when a metafield is created per a specified channel. + type: object + properties: + scope: + type: string + store_id: + type: string + data: + type: object + properties: + metafield_id: + type: integer + resource_id: + type: string + hash: + type: string + created_at: + type: integer + producer: + type: string diff --git a/models/webhooks/store_channel_metafield_deleted.yml b/models/webhooks/store_channel_metafield_deleted.yml new file mode 100644 index 000000000..6ce0f2285 --- /dev/null +++ b/models/webhooks/store_channel_metafield_deleted.yml @@ -0,0 +1,23 @@ +type: object +properties: + store/channel/metafield/deleted: + description: Fires when a metafield is deleted per a specified channel. + type: object + properties: + scope: + type: string + store_id: + type: string + data: + type: object + properties: + metafield_id: + type: integer + resource_id: + type: string + hash: + type: string + created_at: + type: integer + producer: + type: string diff --git a/models/webhooks/store_channel_metafield_updated.yml b/models/webhooks/store_channel_metafield_updated.yml new file mode 100644 index 000000000..8dd1c6758 --- /dev/null +++ b/models/webhooks/store_channel_metafield_updated.yml @@ -0,0 +1,23 @@ +type: object +properties: + store/channel/metafield/updated: + description: Fires when a metafield is updated per a specified channel. + type: object + properties: + scope: + type: string + store_id: + type: string + data: + type: object + properties: + metafield_id: + type: integer + resource_id: + type: string + hash: + type: string + created_at: + type: integer + producer: + type: string diff --git a/models/webhooks/store_customer_address_created.yml b/models/webhooks/store_customer_address_created.yml index 45e08347e..be2486b4f 100644 --- a/models/webhooks/store_customer_address_created.yml +++ b/models/webhooks/store_customer_address_created.yml @@ -1,7 +1,7 @@ type: object properties: store/customer/address/created: - description: Customer address is created + description: Fires when a customer address is created type: object properties: scope: diff --git a/models/webhooks/store_customer_address_deleted.yml b/models/webhooks/store_customer_address_deleted.yml index 073c9cdad..63de5f7a6 100644 --- a/models/webhooks/store_customer_address_deleted.yml +++ b/models/webhooks/store_customer_address_deleted.yml @@ -1,7 +1,7 @@ type: object properties: store/customer/address/deleted: - description: Customer address is deleted + description: Fires when a customer address is deleted type: object properties: scope: diff --git a/models/webhooks/store_customer_address_updated.yml b/models/webhooks/store_customer_address_updated.yml index 7e8b9345d..a9058e83b 100644 --- a/models/webhooks/store_customer_address_updated.yml +++ b/models/webhooks/store_customer_address_updated.yml @@ -1,7 +1,7 @@ type: object properties: store/customer/address/updated: - description: Customer address is updated + description: Fires when a customer address is updated type: object properties: scope: diff --git a/models/webhooks/store_customer_deleted.yml b/models/webhooks/store_customer_deleted.yml index 0076287a9..ff9ef2c59 100644 --- a/models/webhooks/store_customer_deleted.yml +++ b/models/webhooks/store_customer_deleted.yml @@ -1,7 +1,7 @@ type: object properties: store/customer/deleted: - description: Customer is deleted + description: Fires when a customer is deleted type: object properties: scope: diff --git a/models/webhooks/store_customer_payment_instrument_default_updated.yml b/models/webhooks/store_customer_payment_instrument_default_updated.yml index b0b6246c1..9b66d9414 100644 --- a/models/webhooks/store_customer_payment_instrument_default_updated.yml +++ b/models/webhooks/store_customer_payment_instrument_default_updated.yml @@ -1,7 +1,7 @@ type: object properties: store/customer/payment/instrument/default/updated: - description: Customer default payment instrument is updated + description: Fires when a customer default payment instrument is updated type: object properties: scope: diff --git a/models/webhooks/store_customer_updated.yml b/models/webhooks/store_customer_updated.yml index bfc531d0e..8335dd95f 100644 --- a/models/webhooks/store_customer_updated.yml +++ b/models/webhooks/store_customer_updated.yml @@ -1,7 +1,12 @@ type: object properties: store/customer/updated: - description: Customer is updated. Does not currently track changes to the customer address. + description: |- + Fires when a customer is updated. It does not currently track changes to the customer address. + + + Tracks changes to customer attributes only if you make the changes through the control panel. This change triggers the same event `type` and payload as updating a customer; the payload does not include customer attributes. + type: object properties: scope: diff --git a/models/webhooks/store_information_updated.yml b/models/webhooks/store_information_updated.yml index 3a387a9ef..3833efaed 100644 --- a/models/webhooks/store_information_updated.yml +++ b/models/webhooks/store_information_updated.yml @@ -1,7 +1,7 @@ type: object properties: store/information/updated: - description: Occurs when changes are made to store settings. For a full list of fields that can trigger this event, see Store information updated events below + description: Fires when changes are made to store settings. For a full list of fields that can trigger this event, see the store information updated events that follow. type: object properties: scope: diff --git a/models/webhooks/store_inventory_location_created.yml b/models/webhooks/store_inventory_location_created.yml new file mode 100644 index 000000000..a605eb343 --- /dev/null +++ b/models/webhooks/store_inventory_location_created.yml @@ -0,0 +1,21 @@ +type: object +properties: + store/inventory/location/created: + description: Location is created. + type: object + properties: + producer: + type: string + hash: + type: string + created_at: + type: integer + store_id: + type: string + scope: + type: string + data: + type: object + properties: + location_id: + type: integer diff --git a/models/webhooks/store_inventory_location_metafield_created.yml b/models/webhooks/store_inventory_location_metafield_created.yml new file mode 100644 index 000000000..144f35ff7 --- /dev/null +++ b/models/webhooks/store_inventory_location_metafield_created.yml @@ -0,0 +1,22 @@ +properties: + store/inventory/location/metafield/created: + description: Fires when a new inventory location metafield is created. + type: object + properties: + scope: + type: string + store_id: + type: string + data: + type: object + properties: + metafield_id: + type: integer + resource_id: + type: string + hash: + type: string + created_at: + type: integer + producer: + type: string diff --git a/models/webhooks/store_inventory_location_metafield_deleted.yml b/models/webhooks/store_inventory_location_metafield_deleted.yml new file mode 100644 index 000000000..3834bbc99 --- /dev/null +++ b/models/webhooks/store_inventory_location_metafield_deleted.yml @@ -0,0 +1,22 @@ +properties: + store/inventory/location/metafield/deleted: + description: Fires when a inventory location metafield is deleted. + type: object + properties: + scope: + type: string + store_id: + type: string + data: + type: object + properties: + metafield_id: + type: integer + resource_id: + type: string + hash: + type: string + created_at: + type: integer + producer: + type: string diff --git a/models/webhooks/store_inventory_location_metafield_updated.yml b/models/webhooks/store_inventory_location_metafield_updated.yml new file mode 100644 index 000000000..dfe40b974 --- /dev/null +++ b/models/webhooks/store_inventory_location_metafield_updated.yml @@ -0,0 +1,23 @@ +type: object +properties: + store/inventory/location/metafield/updated: + description: Fires when an existing inventory location metafield is updated. + type: object + properties: + scope: + type: string + store_id: + type: string + data: + type: object + properties: + metafield_id: + type: integer + resource_id: + type: string + hash: + type: string + created_at: + type: integer + producer: + type: string diff --git a/models/webhooks/store_inventory_location_updated.yml b/models/webhooks/store_inventory_location_updated.yml new file mode 100644 index 000000000..93f8ccbce --- /dev/null +++ b/models/webhooks/store_inventory_location_updated.yml @@ -0,0 +1,21 @@ +type: object +properties: + store/inventory/location/updated: + description: Location is updated. + type: object + properties: + producer: + type: string + hash: + type: string + created_at: + type: integer + store_id: + type: string + scope: + type: string + data: + type: object + properties: + location_id: + type: integer diff --git a/models/webhooks/store_metafield_created.yml b/models/webhooks/store_metafield_created.yml new file mode 100644 index 000000000..0cfe1336e --- /dev/null +++ b/models/webhooks/store_metafield_created.yml @@ -0,0 +1,25 @@ +type: object +properties: + store/metafield/created: + description: This webhook will fire whenever a new metafield on any object is created. + type: object + properties: + scope: + type: string + store_id: + type: string + data: + type: object + properties: + metafield_id: + type: integer + resource_id: + type: string + resource_type: + type: string + hash: + type: string + created_at: + type: integer + producer: + type: string diff --git a/models/webhooks/store_metafield_deleted.yml b/models/webhooks/store_metafield_deleted.yml new file mode 100644 index 000000000..f0bc56cbc --- /dev/null +++ b/models/webhooks/store_metafield_deleted.yml @@ -0,0 +1,25 @@ +type: object +properties: + store/metafield/deleted: + description: When a metafield is deleted. + type: object + properties: + scope: + type: string + store_id: + type: string + data: + type: object + properties: + metafield_id: + type: integer + resource_id: + type: string + resource_type: + type: string + hash: + type: string + created_at: + type: integer + producer: + type: string diff --git a/models/webhooks/store_metafield_updated.yml b/models/webhooks/store_metafield_updated.yml new file mode 100644 index 000000000..d61e00380 --- /dev/null +++ b/models/webhooks/store_metafield_updated.yml @@ -0,0 +1,25 @@ +type: object +properties: + store/metafield/updated: + description: Fires when an already created metafield is updated. Any changes to an existing metafield on any object (such as inventory, carts, brands, categories, channels, orders, ShipperHQ, etc.) will fire this webhook. + type: object + properties: + scope: + type: string + store_id: + type: string + data: + type: object + properties: + metafield_id: + type: integer + resource_id: + type: string + resource_type: + type: string + hash: + type: string + created_at: + type: integer + producer: + type: string diff --git a/models/webhooks/store_order_created.yml b/models/webhooks/store_order_created.yml index eb4c5fc6a..16e843b45 100644 --- a/models/webhooks/store_order_created.yml +++ b/models/webhooks/store_order_created.yml @@ -1,7 +1,7 @@ type: object properties: store/order/created: - description: Fires if an order is created using the control panel, an app or via the API + description: Fires when an order is created either in the control panel or by API. type: object properties: scope: diff --git a/models/webhooks/store_order_metafield_created.yml b/models/webhooks/store_order_metafield_created.yml new file mode 100644 index 000000000..b31c20d97 --- /dev/null +++ b/models/webhooks/store_order_metafield_created.yml @@ -0,0 +1,23 @@ +type: object +properties: + store/order/metafield/created: + description: Fires if an order metafield is created using the control panel, an app, or the API. + type: object + properties: + scope: + type: string + store_id: + type: string + data: + type: object + properties: + metafield_id: + type: integer + resource_id: + type: string + hash: + type: string + created_at: + type: integer + producer: + type: string diff --git a/models/webhooks/store_order_metafield_deleted.yml b/models/webhooks/store_order_metafield_deleted.yml new file mode 100644 index 000000000..67eb5ab80 --- /dev/null +++ b/models/webhooks/store_order_metafield_deleted.yml @@ -0,0 +1,23 @@ +type: object +properties: + store/order/metafield/deleted: + description: An order metafield is deleted. + type: object + properties: + scope: + type: string + store_id: + type: string + data: + type: object + properties: + metafield_id: + type: integer + resource_id: + type: string + hash: + type: string + created_at: + type: integer + producer: + type: string diff --git a/models/webhooks/store_order_metafield_updated.yml b/models/webhooks/store_order_metafield_updated.yml new file mode 100644 index 000000000..76318ffe6 --- /dev/null +++ b/models/webhooks/store_order_metafield_updated.yml @@ -0,0 +1,23 @@ +type: object +properties: + store/order/metafield/updated: + description: Fires when an existing order metafield is updated. Any changes to an existing order metafield will fire this webhook. + type: object + properties: + scope: + type: string + store_id: + type: string + data: + type: object + properties: + metafield_id: + type: integer + resource_id: + type: string + hash: + type: string + created_at: + type: integer + producer: + type: string diff --git a/models/webhooks/store_order_statusUpdated.yml b/models/webhooks/store_order_statusUpdated.yml index 812ef24f2..44563c4f0 100644 --- a/models/webhooks/store_order_statusUpdated.yml +++ b/models/webhooks/store_order_statusUpdated.yml @@ -1,7 +1,7 @@ type: object properties: store/order/statusUpdated: - description: This will only fire if the order status has changed. Such as Pending to Awaiting Payment + description: Fires when the order status has changed, such as from Pending to Awaiting Payment. type: object properties: scope: diff --git a/models/webhooks/store_order_transaction_created.yml b/models/webhooks/store_order_transaction_created.yml new file mode 100644 index 000000000..e3ceeb903 --- /dev/null +++ b/models/webhooks/store_order_transaction_created.yml @@ -0,0 +1,24 @@ +properties: + store/order/transaction/created: + description: Fires when a new order transaction is created. + type: object + properties: + scope: + type: string + store_id: + type: string + data: + type: object + properties: + type: + type: string + order_id: + type: integer + transaction_id: + type: string + hash: + type: string + created_at: + type: integer + producer: + type: string diff --git a/models/webhooks/store_order_transaction_updated.yml b/models/webhooks/store_order_transaction_updated.yml new file mode 100644 index 000000000..9ce2d7fbf --- /dev/null +++ b/models/webhooks/store_order_transaction_updated.yml @@ -0,0 +1,24 @@ +properties: + store/order/transaction/updated: + description: Fires when a new order transaction is updated. + type: object + properties: + scope: + type: string + store_id: + type: string + data: + type: object + properties: + type: + type: string + order_id: + type: integer + transaction_id: + type: string + hash: + type: string + created_at: + type: integer + producer: + type: string diff --git a/models/webhooks/store_order_updated.yml b/models/webhooks/store_order_updated.yml index 8159819eb..257337511 100644 --- a/models/webhooks/store_order_updated.yml +++ b/models/webhooks/store_order_updated.yml @@ -1,7 +1,7 @@ type: object properties: store/order/updated: - description: Fires when an already created order is updated. Any changes to an existing order will fire this webhook. Updates can include changing the status, updating a coupon or changing an address. + description: Fires when an already created order is updated. Any change to an existing order fires this webhook. Updates can include changing the status, updating a coupon, or changing an address. type: object properties: scope: diff --git a/models/webhooks/store_product_inventory_order_updated.yml b/models/webhooks/store_product_inventory_order_updated.yml index e7e6863f2..c32b90371 100644 --- a/models/webhooks/store_product_inventory_order_updated.yml +++ b/models/webhooks/store_product_inventory_order_updated.yml @@ -1,7 +1,10 @@ type: object properties: store/product/inventory/order/updated: - description: Fires if a product’s inventory is decremented or incremented, including when an order is placed. Webhook responds to inventory updates made using the control panel, CSV import, API or an app. + description: |- + Fires when _base product_ inventory levels change in response to the order-related events configured in [Inventory settings](/docs/rest-management/settings/inventory#get-inventory-settings). For example, stock levels can change when you either place or complete/ship an order. Stock levels can also change when you refund or cancel an order. Global settings apply when inventory changes through a [manual order](https://support.bigcommerce.com/s/article/Creating-a-Manual-Order?language=en_US). The settings for a channel apply when inventory changes through an order in a channel. + + The webhook always fires for products without variants. For products with variants, the webhook only fires when the product's inventory properties are configured to track by _product_. type: object properties: scope: diff --git a/models/webhooks/store_product_inventory_updated.yml b/models/webhooks/store_product_inventory_updated.yml index dfc78055e..2b457c594 100644 --- a/models/webhooks/store_product_inventory_updated.yml +++ b/models/webhooks/store_product_inventory_updated.yml @@ -1,7 +1,12 @@ type: object properties: store/product/inventory/updated: - description: Product inventory is updated. + description: |- + Fires when inventory levels change for a _base product_. For products without variants, the webhook fires regardless of how you track inventory. + + For products with variants, the webhook only fires when the product's inventory properties are configured to track by _product_ and the _product-level_ inventory changes. + + Inventory updates made in the control panel and by API trigger the webhook. This includes changes made by apps. In the control panel, you can bulk import inventory updates or make inventory updates to single products on the **Products > View** page. type: object properties: scope: diff --git a/models/webhooks/store_product_metafield_created.yml b/models/webhooks/store_product_metafield_created.yml new file mode 100644 index 000000000..b0e8a3aa6 --- /dev/null +++ b/models/webhooks/store_product_metafield_created.yml @@ -0,0 +1,25 @@ +type: object +properties: + store/product/metafield/created: + description: Fires when a new product metafield is created. + type: object + properties: + scope: + type: string + store_id: + type: string + data: + type: object + properties: + metafield_id: + type: integer + resource_id: + type: string + resource_type: + type: string + hash: + type: string + created_at: + type: integer + producer: + type: string diff --git a/models/webhooks/store_product_metafield_deleted.yml b/models/webhooks/store_product_metafield_deleted.yml new file mode 100644 index 000000000..464126be6 --- /dev/null +++ b/models/webhooks/store_product_metafield_deleted.yml @@ -0,0 +1,25 @@ +type: object +properties: + store/product/metafield/deleted: + description: Occurs when a product metafield is deleted. + type: object + properties: + scope: + type: string + store_id: + type: string + data: + type: object + properties: + metafield_id: + type: integer + resource_id: + type: string + resource_type: + type: string + hash: + type: string + created_at: + type: integer + producer: + type: string diff --git a/models/webhooks/store_product_metafield_updated.yml b/models/webhooks/store_product_metafield_updated.yml new file mode 100644 index 000000000..7985090fd --- /dev/null +++ b/models/webhooks/store_product_metafield_updated.yml @@ -0,0 +1,25 @@ +type: object +properties: + store/product/metafield/updated: + description: Occurs when product metafield details are edited. + type: object + properties: + scope: + type: string + store_id: + type: string + data: + type: object + properties: + metafield_id: + type: integer + resource_id: + type: string + resource_type: + type: string + hash: + type: string + created_at: + type: integer + producer: + type: string diff --git a/models/webhooks/store_product_updated.yml b/models/webhooks/store_product_updated.yml index e0a828b75..63b9a44e8 100644 --- a/models/webhooks/store_product_updated.yml +++ b/models/webhooks/store_product_updated.yml @@ -1,7 +1,7 @@ type: object properties: store/product/updated: - description: Occurs when product details are edited. For a full list of product fields that trigger an updated event, see Product updated events below + description: Fires when product details are edited. For a full list of product fields that trigger an updated event, see the product updated events that follow. type: object properties: scope: diff --git a/models/webhooks/store_sku_inventory_order_updated.yml b/models/webhooks/store_sku_inventory_order_updated.yml index 835793648..dae191e0d 100644 --- a/models/webhooks/store_sku_inventory_order_updated.yml +++ b/models/webhooks/store_sku_inventory_order_updated.yml @@ -1,7 +1,10 @@ type: object properties: store/sku/inventory/order/updated: - description: This will fire when the inventory is updated via API, the control panel, when an order is placed and when an order is refunded and the inventory is returned to stock. This hook will fire based on a store’s Inventory settings. + description: |- + Fires when _variant_ inventory levels change in response to the order-related events configured in [Inventory settings](/docs/rest-management/settings/inventory#get-inventory-settings). For example, stock levels can change when you either place or complete/ship an order. Stock levels can also change when you refund or cancel an order. Global settings apply when inventory changes through a [manual order](https://support.bigcommerce.com/s/article/Creating-a-Manual-Order?language=en_US). The settings for a channel apply when inventory changes through an order in a channel. + + The webhook does not fire for products without variants. For products with variants, the webhook only fires when the product's inventory properties are configured to track by _variant_. type: object properties: scope: diff --git a/models/webhooks/store_sku_inventory_updated.yml b/models/webhooks/store_sku_inventory_updated.yml index 9425652a0..5f1aff188 100644 --- a/models/webhooks/store_sku_inventory_updated.yml +++ b/models/webhooks/store_sku_inventory_updated.yml @@ -1,7 +1,12 @@ type: object properties: store/sku/inventory/updated: - description: SKU is updated + description: |- + Fires when inventory levels change for a _variant_. This webhook does not fire for products without variants. + + For products with variants, the webhook only fires when the product's inventory properties are configured to track by _variant_ and the _variant-level_ inventory changes. + + Inventory updates made in the control panel and by API trigger the webhook. This includes changes made by apps. In the control panel, you can bulk import inventory updates or make inventory updates to single products on the **Products > View** page. type: object properties: scope: diff --git a/models/webhooks/store_variant_metafield_created.yml b/models/webhooks/store_variant_metafield_created.yml new file mode 100644 index 000000000..5321fedc2 --- /dev/null +++ b/models/webhooks/store_variant_metafield_created.yml @@ -0,0 +1,25 @@ +type: object +properties: + store/variant/metafield/created: + description: Occurs when a new product variant metafield is created. + type: object + properties: + scope: + type: string + store_id: + type: string + data: + type: object + properties: + metafield_id: + type: integer + resource_id: + type: string + resource_type: + type: string + hash: + type: string + created_at: + type: integer + producer: + type: string diff --git a/models/webhooks/store_variant_metafield_deleted.yml b/models/webhooks/store_variant_metafield_deleted.yml new file mode 100644 index 000000000..25f0b28d0 --- /dev/null +++ b/models/webhooks/store_variant_metafield_deleted.yml @@ -0,0 +1,25 @@ +type: object +properties: + store/variant/metafield/deleted: + description: Occurs when a product variant metafield is deleted. + type: object + properties: + scope: + type: string + store_id: + type: string + data: + type: object + properties: + metafield_id: + type: integer + resource_id: + type: string + resource_type: + type: string + hash: + type: string + created_at: + type: integer + producer: + type: string diff --git a/models/webhooks/store_variant_metafield_updated.yml b/models/webhooks/store_variant_metafield_updated.yml new file mode 100644 index 000000000..291e343ac --- /dev/null +++ b/models/webhooks/store_variant_metafield_updated.yml @@ -0,0 +1,25 @@ +type: object +properties: + store/variant/metafield/updated: + description: Occurs when product variant metafield details are edited. + type: object + properties: + scope: + type: string + store_id: + type: string + data: + type: object + properties: + metafield_id: + type: integer + resource_id: + type: string + resource_type: + type: string + hash: + type: string + created_at: + type: integer + producer: + type: string diff --git a/package-lock.json b/package-lock.json index a22c54782..4e3f8f486 100644 --- a/package-lock.json +++ b/package-lock.json @@ -3322,9 +3322,9 @@ } }, "node_modules/word-wrap": { - "version": "1.2.3", - "resolved": "https://registry.npmjs.org/word-wrap/-/word-wrap-1.2.3.tgz", - "integrity": "sha512-Hz/mrNwitNRh/HUAtM/VT/5VH+ygD6DV7mYKZAtHOrbs8U7lvPS6xf7EJKMF0uW1KJCl0H701g3ZGus+muE5vQ==", + "version": "1.2.4", + "resolved": "https://registry.npmjs.org/word-wrap/-/word-wrap-1.2.4.tgz", + "integrity": "sha512-2V81OA4ugVo5pRo46hAoD2ivUJx8jXmWXfUkY4KFNw0hEptvN0QfH3K4nHiwzGeKl5rFKedV48QVoqYavy4YpA==", "dev": true, "engines": { "node": ">=0.10.0" diff --git a/pull_request_template.md b/pull_request_template.md new file mode 100644 index 000000000..188cdb296 --- /dev/null +++ b/pull_request_template.md @@ -0,0 +1,11 @@ +# [DEVDOCS-] +{Ticket number or summary of work} + +## What changed? +Provide a bulleted list in the present tense +* + +## Anything else? +Add related PRs, salient notes, ticket numbers, etc. + +ping {names} diff --git a/reference/abandoned_cart_emails.v3.yaml b/reference/abandoned_cart_emails.v3.yaml index eb8a5efc4..030a7d683 100644 --- a/reference/abandoned_cart_emails.v3.yaml +++ b/reference/abandoned_cart_emails.v3.yaml @@ -363,7 +363,7 @@ components: body: type: string example: '''Complete your purchase <a href="{{ notification.checkout_link }}">{{notification.checkout.link}}''' - translation: + translations: type: array items: $ref: '#/components/schemas/TranslationDefinition' @@ -506,15 +506,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header diff --git a/reference/abandoned_carts.v3.yml b/reference/abandoned_carts.v3.yml index 4f3716052..b53d3f156 100644 --- a/reference/abandoned_carts.v3.yml +++ b/reference/abandoned_carts.v3.yml @@ -3,7 +3,7 @@ info: version: '' title: Abandoned Carts description: |- - Use `/abandoned-carts/{token}` on headless storefronts to retrieve the `cart_id` using the abandoned cart `token` passed to the storefront when a shopper clicks an abandoned cart email link. Once the `cart_id` has been retrieved, your application can use it to fetch and display information about the cart to the shopper using the Storefront Cart API and/or Store Management Cart API. + Use `/abandoned-carts/{token}` on headless storefronts to retrieve the `cart_id` using the abandoned cart `token` passed to the storefront when a shopper clicks an abandoned cart email link. Once the cart ID has been retrieved, your application can use it to fetch and display information about the cart to the shopper using the REST Storefront API, the REST Management API, or the GraphQL Storefront API. termsOfService: 'https://www.bigcommerce.com/terms' contact: name: BigCommerce @@ -87,13 +87,6 @@ paths: operationId: getChannelAbandonedCartSettings tags: - Abandoned Carts Settings - parameters: - - name: channel_id - description: The channel ID of the settings overrides - in: path - required: true - schema: - type: integer responses: '200': description: OK @@ -120,12 +113,6 @@ paths: tags: - Abandoned Carts Settings parameters: - - name: channel_id - description: The channel ID of the settings overrides - in: path - required: true - schema: - type: integer - $ref: '#/components/parameters/ContentType' requestBody: required: true @@ -154,13 +141,13 @@ paths: $ref: '#/components/schemas/ErrorResponse' security: [] parameters: - - $ref: '#/components/parameters/Accept' - - schema: - type: string - name: channel_id + - name: channel_id + description: The channel ID of the settings overrides in: path required: true + schema: + type: integer '/abandoned-carts/{token}': get: responses: @@ -336,15 +323,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header schemas: @@ -385,7 +372,7 @@ components: properties: cart_id: type: string - description: The `cart_id` of the abandoned cart. Can be used to display the abandoned cart to the customer using storefront cart or + description: The `cart_id` of the abandoned cart. Can be used to display the abandoned cart to the customer using storefront cart or server-to-server cart APIs. x-internal: false AbandonedCartSettings: description: Represents all settings related to the abandoned cart functionality of a store diff --git a/reference/carts.sf.yml b/reference/carts.sf.yml index e646ac5cb..7b0adb56f 100644 --- a/reference/carts.sf.yml +++ b/reference/carts.sf.yml @@ -3,11 +3,16 @@ info: version: Storefront title: Storefront Carts description: |- - Manage cart operations and data using frontend JavaScript on BigCommerce stencil powered storefronts. + Manage cart operations and data using frontend JavaScript on BigCommerce Stencil-powered storefronts. - For info about API accounts, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). + For info about API accounts, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). - For info about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#same-origin-cors-authentication). + For info about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#same-origin-cors-authentication). + termsOfService: 'https://www.bigcommerce.com/terms' + contact: + name: BigCommerce + url: 'https://www.bigcommerce.com' + email: support@bigcommerce.com servers: - url: 'https://{store_domain}/api/storefront' variables: @@ -66,6 +71,20 @@ paths: - optionId: 10 optionValue: Some Text Value locale: en + With Gift Wrapping: + value: + lineItems: + - quantity: 2 + productId: 230 + optionSelections: + - optionId: 10 + optionValue: Some Text Value + giftWrapping: + wrapTogether: true + wrapDetails: + - id: 1 + message: "Happy Birthday" + locale: en required: true responses: '200': @@ -104,10 +123,10 @@ paths: description: |- Adds a line items to the *Cart*. - - > #### Note + > #### Notes > * Substitute your storefront domain for `yourstore.example.com`. > * The Send a Test Request feature is not currently supported for this endpoint. + > * Please note that this API endpoint is not concurrent safe, meaning multiple simultaneous requests could result in unexpected and inconsistent results. operationId: addCartLineItem parameters: @@ -155,6 +174,17 @@ paths: optionValue: 117 - optionId: 11 optionValue: 125 + With Gift Wrapping: + value: + lineItems: + - quantity: 2 + productId: 230 + variantId: 124 + giftWrapping: + wrapTogether: true + wrapDetails: + - id: 1 + message: "Happy Birthday" description: '' '/carts/{cartId}/items/{itemId}': put: @@ -164,12 +194,13 @@ paths: description: |- Updates a *Cart* line item. Updates an existing, single line item quantity and the price of custom items in a cart. - If a modified product or variant needs to be changed or updated, you can remove and re-add the product to the cart with the correct variants using the [Delete Cart Line Item](/docs/rest-storefront/carts/cart-items#delete-cart-line-item) and the [Add Cart Line Items](/docs/rest-storefront/carts/cart-items#add-cart-line-items) endpoints. + If a modified product or variant needs to be changed or updated, you can remove and re-add the product to the cart with the correct variants using the [Delete Cart Line Item](/docs/rest-storefront/carts/cart-items#delete-cart-line-item) and the [Add Cart Line Items](/docs/rest-storefront/carts/cart-items#add-cart-line-items) endpoints. You can also use carts mutations that are part of the [GraphQL Storefront API](/docs/storefront/cart-checkout/guide/graphql-storefront). - > #### Note + > #### Notes > * Substitute your storefront domain for `yourstore.example.com`. - > * The Send a Test Request feature is not currently supported for this endpoint. + > * The Send a Test Request feature is not currently supported for this endpoint. + > * Please note that this API endpoint is not concurrent safe, meaning multiple simultaneous requests could result in unexpected and inconsistent results. operationId: updateCartLineItem parameters: @@ -227,6 +258,24 @@ paths: - optionId: 125 optionValue: 127 locale: en + With Gift Wrapping: + value: + lineItem: + quantity: 2 + productId: 230 + variantId: 124 + giftWrapping: + wrapTogether: true + wrapDetails: + - id: 1 + message: "Happy Birthday" + With null Gift Wrapping (will delete current gift wrapping): + value: + lineItem: + quantity: 2 + productId: 230 + variantId: 124 + giftWrapping: null required: true responses: '200': @@ -372,7 +421,7 @@ components: description: ID of the applied discount. x-internal: false responseCart: - description: Cart object used in storefront cart responses. + description: Cart object used in REST Storefront API cart responses. title: Cart Read type: object properties: @@ -504,6 +553,39 @@ components: type: string description: 'Currently supports `Birthday`, `Boy`, `Celebration`, `Christmas`, `General`, and `Girl`.' x-internal: false + requestPostOrPutGiftWrapping: + title: Gift Wrapping Request Data + required: + - wrapTogether + - wrapDetails + type: object + nullable: true + description: if passing null, it will remove the current gift wrapping for the item + properties: + wrapTogether: + type: boolean + description: Boolean value that specifies whether items whether items should be wrapped together or wrapped individually. + example: true + wrapDetails: + type: array + description: |- + Details for the gift wrapping option selected. This can be specified for each line item or together based on wrapTogether value. + If wrapTogether is false, each element in the wrapDetails array determines each item's specific wrapping. + (e.g if this line item has 6 quantity, you can pass at maximum 6 elements for the array to spefified each one's wrapping) + If wrapTogether is true, we will only use 1st element in the wrapDetails array to determine what to be wrapped + items: + type: object + required: + - id + properties: + id: + type: integer + description: Identifier of the gift wrapping option selected. + example: 0 + message: + type: string + description: Custom gift message. + example: Happy Birthday LineItemsRequest: title: requestLineItems oneOf: @@ -605,7 +687,7 @@ components: readOnly: true id: type: string - description: Id of the custom item + description: ID of the custom item readOnly: true example: f1f3a531-fbcf-439b-bac1-40d5ae5c2bff listPrice: @@ -615,7 +697,7 @@ components: example: 10 name: type: string - description: Item name + description: Name of the custom item. readOnly: true example: Custom Item Name quantity: @@ -624,13 +706,13 @@ components: example: 1 sku: type: string - description: Custom item sku + description: SKU of the custom item. readOnly: true example: SM-456 description: |- **Read Only** - This will return in the Cart Response if the Cart was created using the [Store Management Carts API](/docs/rest-management/carts). A custom item can only be added to a cart using the Server to Server API. + This will return in the Cart Response if the Cart was created using the [REST Management API](/docs/rest-management/carts). A custom item can only be added to a cart using the REST Management API. x-internal: false responseCartLineItemsDigitalItems: title: Item Digital @@ -919,6 +1001,8 @@ components: quantity: type: number description: Quantity of this item. + giftWrapping: + $ref: '#/components/schemas/requestPostOrPutGiftWrapping' required: - productId - quantity @@ -933,54 +1017,13 @@ components: variantId: type: number description: ID of the variant. + giftWrapping: + $ref: '#/components/schemas/requestPostOrPutGiftWrapping' required: - productId - quantity - variantId - title: Product with a variant - - properties: - productId: - type: number - description: ID of the product. - quantity: - type: number - description: Quantity of this item. - variantId: - type: number - optionSelections: - type: array - description: Array of `OptionSelection` objects. - items: - oneOf: - - type: object - properties: - optionId: - type: number - description: 'ID of the option, same as the `nameId`.' - example: 10 - - type: object - properties: - optionValue: - description: 'Value of the option, same as the `valueId`.' - oneOf: - - type: string - example: Small - - type: number - example: 127 - - type: object - properties: - month: - type: string - day: - type: string - year: - type: string - required: - - productId - - quantity - - variantId - - optionSelections - title: Custom product + title: Product with a variant x-examples: example-1: productId: 0 @@ -1039,13 +1082,7 @@ components: - discountedAmount: 0 id: string lineItems: - customItems: - - extendedListPrice: 0 - id: f1f3a531-fbcf-439b-bac1-40d5ae5c2bff - listPrice: 10 - name: Custom Item Name - quantity: 1 - sku: SM-456 + customItems: [] digitalItems: - options: - name: string @@ -1148,13 +1185,7 @@ components: - discountedAmount: 0 id: string lineItems: - customItems: - - extendedListPrice: 0 - id: f1f3a531-fbcf-439b-bac1-40d5ae5c2bff - listPrice: 10 - name: Custom Item Name - quantity: 1 - sku: SM-456 + customItems: [] digitalItems: - options: - name: string @@ -1257,13 +1288,7 @@ components: - discountedAmount: 0 id: string lineItems: - customItems: - - extendedListPrice: 0 - id: f1f3a531-fbcf-439b-bac1-40d5ae5c2bff - listPrice: 10 - name: Custom Item Name - quantity: 1 - sku: SM-456 + customItems: [] digitalItems: - options: - name: string @@ -1426,119 +1451,7 @@ components: - discountedAmount: 0 id: string lineItems: - customItems: - - extendedListPrice: 0 - id: f1f3a531-fbcf-439b-bac1-40d5ae5c2bff - listPrice: 10 - name: Custom Item Name - quantity: 1 - sku: SM-456 - digitalItems: - - options: - - name: string - nameId: 0 - value: string - valueId: 0 - brand: string - couponAmount: 0 - discountAmount: 0 - discounts: - - discountedAmount: 0 - id: 0 - extendedListPrice: 0 - extendedSalePrice: 0 - id: '4' - imageUrl: 'http://example.com' - isTaxable: true - originalPrice: 0 - listPrice: 0 - name: string - parentId: '6' - productId: 0 - quantity: 0 - salePrice: 0 - sku: string - url: 'http://example.com' - variantId: 7 - giftCertificates: - - amount: 0 - id: string - isTaxable: true - message: string - name: string - recipient: - email: user@example.com - name: string - sender: - email: user@example.com - name: string - theme: string - physicalItems: - - options: - - name: string - nameId: 0 - value: string - valueId: 0 - brand: string - couponAmount: 0 - discountAmount: 0 - discounts: - - discountedAmount: 0 - id: string - extendedListPrice: 0 - extendedSalePrice: 0 - id: '4' - imageUrl: 'http://example.com' - isTaxable: true - originalPrice: 0 - listPrice: 0 - name: string - parentId: 6 - productId: 0 - quantity: 0 - salePrice: 0 - sku: string - url: 'http://example.com' - variantId: 7 - giftWrapping: null - isShippingRequired: true - createdTime: string - updatedTime: string - locale: string - deleteCarts: - description: '' - content: - application/json: - schema: - $ref: '#/components/schemas/responseCart' - examples: - example-1: - value: - id: string - customerId: 0 - email: string - currency: - code: string - isTaxIncluded: true - baseAmount: 0 - discountAmount: 0 - cartAmount: 0 - coupons: - - code: string - couponType: 0 - discountedAmount: 0 - id: string - discounts: - - discountedAmount: 0 - id: string - lineItems: - customItems: - - extendedListPrice: 0 - id: f1f3a531-fbcf-439b-bac1-40d5ae5c2bff - listPrice: 10 - name: Custom Item Name - quantity: 1 - sku: SM-456 + customItems: [] digitalItems: - options: - name: string @@ -1622,5 +1535,4 @@ components: - lineItems.physicalItems.options - lineItems.digitalItems.options - 'lineItems.digitalItems.options,lineItems.physicalItems.options' - examples: {} diff --git a/reference/carts.v3.yml b/reference/carts.v3.yml index 19a629ca1..2ad220064 100644 --- a/reference/carts.v3.yml +++ b/reference/carts.v3.yml @@ -49,10 +49,10 @@ paths: * A cart can be created by adding an existing **catalog item** or a **custom item**. * Carts are valid for **30 days** from the **last modification** (this includes creating the cart or editing the cart). * If a product has modifiers, use the `option_selections` array to describe the **modifier** selection(s). - * The format and data type of a cart’s `option_value` are defined by the `value_data` object of a product’s [variant option value](/docs/rest-management/catalog/product-variant-option-values), [modifier value](/docs/rest-management/catalog/product-modifier-values), or a combination of both. - * Redirect URLs can only be generated from carts that were created using the **Server-to-Server Carts API**. + * The format and data type of a cart’s `option_value` are defined by the `value_data` object of a product’s [variant option value](/docs/rest-catalog/product-variant-options/values), [modifier value](/docs/rest-catalog/product-modifiers/values), or a combination of both. + * Redirect URLs can only be generated from carts that were created using the **REST Management API**. * To get cart `redirect_urls` in the response, append the following query parameter to the request URL: `include=redirect_urls`. Redirect URLs point to either a shared checkout domain or a channel-specific domain, depending on the storefront configuration. - * To restore a cart that was created by a shopper or through the Storefront Cart API, first recreate the cart using the Server to Server Cart API. + * To restore a cart that was created by a shopper or through a Storefront API, first recreate the cart using the **REST Management API**. * To get cart `promotions` in the response, append the following query parameter to the request URL: `include=promotions.banners`. parameters: - name: include @@ -77,6 +77,7 @@ paths: $ref: '#/components/schemas/CartCreatePostData' examples: Simple Product: + summary: Creating a cart by adding a simple product without option selections. value: customer_id: 0 line_items: @@ -89,6 +90,7 @@ paths: code: USD locale: en-US Cart with a variant: + summary: Creating a cart with a product that can be specified purely by a variant, without any other required options. value: customer_id: 0 line_items: @@ -96,12 +98,18 @@ paths: product_id: 118 list_price: 25 variant_id: 140 - name: shirt + name: قميص + option_selections: + - option_id: 125 + option_value: 127 + name: بحجم + value: صغير channel_id: 1 currency: - code: USD - locale: en-US + code: JOD + locale: ar-JO Cart with date option: + summary: Creating a cart using a date option. value: line_items: - quantity: 1 @@ -109,8 +117,14 @@ paths: variant_id: 144 option_selections: - option_id: 147 - option_value: '{“day”:”01”, “month”:”02”, “year”:”2020”}' - 'Cart with variant, a checkbox, and a pick list modifier': + option_value: '{“día”:”01”, “mes”:”02”, “año”:”2020”}' + name: calendario + value: 2023 + currency: + code: MXN + locale: es-MX + Cart with variant, a checkbox, and a pick list modifier: + summary: Creating a cart with a variant, a checkbox, and an added picklist modifier. value: customer_id: 0 line_items: @@ -119,20 +133,21 @@ paths: product_id: 118 list_price: 30 name: shirt - options: - - name: Size - nameId: 125 - value: Large - valueId: 127 + option_selections: + - name: Color + value: Red + option_id: 133 + option_value: 149 - name: Add a $5 Donation - nameId: 126 - value: 'No' - valueId: 129 + value: No + option_id: 126 + option_value: 129 channel_id: 1 currency: - code: usd - locale: en + code: AUD + locale: en-AU Custom item: + summary: Creating a cart using a custom item. value: customer_id: 0 line_items: [] @@ -148,7 +163,7 @@ paths: message: Happy Birthday gift_certificates: - name: Tobi Day - theme: Birthday + theme: birthday.html amount: 1 quantity: 1 sender: @@ -161,15 +176,8 @@ paths: channel_id: 1 currency: code: usd - locale: en + locale: en-US description: |- - **Examples:** - - 1. Creating a cart by adding a simple product (a product without option selections). - 2. Creating a cart with a variant. This works when a product can be specified purely by a variant, without any other required options. - 3. Creating a cart using a date option. The API supports timestamps, “option_value”: 1743570000, and dates as an object literal, “option_value”: {“day”:”01”, “month”:”02”, “year”:”2020”}. - 4. Creating a cart with a variant, a checkbox, and a picklist modifier added. - 5. Creating a cart using a custom item. required: true x-examples: Simple Product: |- @@ -280,6 +288,8 @@ paths: Overriding a product’s `list_price` will make that item ineligible for V3 product level promotions. If a product has modifiers, omit the `variant_id` and instead use the `option_selections` array to describe both the **variant** and the **modifier** selections. + + Please note that this API endpoint is not concurrent safe, meaning multiple simultaneous requests could result in unexpected and inconsistent results. parameters: - name: include in: query @@ -312,7 +322,7 @@ paths: option_value: 'Yes' gift_certificates: - name: Happy Birthday - theme: Birthday + theme: birthday.html amount: 50 quantity: 1 sender: @@ -348,13 +358,13 @@ paths: **Usage Notes** - * Redirect URLs can also be created via **Create a Cart** requests by appending `include=redirect_urls`. + * Redirect URLs can also be created with **Create a Cart** requests by appending `include=redirect_urls`. * A **Carts** redirect URL may only be used once. * Redirect URLs point to either a shared checkout domain or a channel-specific domain, depending on the storefront configuration. * Once a redirect URL has been visited, it will be invalidated and cannot be used again. * If your application requires URLs to be visited more than once, consider generating a fresh one each time you need to restore a cart, and redirecting to the URL from your own application. - * Redirect URLs can be generated only from carts that were created using the Server to Server Cart API and the Storefront Cart API. - * To restore a cart that was created on the storefront, either by a shopper or the Storefront Cart API, first recreate the cart using the Server to Server Cart API. + * Redirect URLs can be generated only from carts that were created using the **REST Management API**. + * To restore a cart that was created on the storefront, either by a shopper or a Storefront API, first recreate the cart using the **REST Management API**. tags: - Redirects responses: @@ -387,6 +397,8 @@ paths: `custom_items` cannot be updated via the API at this time. To update your cart, add a new updated custom item and delete the outdated one. If your cart contains only one line item, perform the add operation before the delete operation. Deleting all line items from the cart will invalidate the cart. + + Please note that this API endpoint is not concurrent safe, meaning multiple simultaneous requests could result in unexpected and inconsistent results. parameters: - name: include in: query @@ -499,7 +511,7 @@ paths: gift_certificates: - id: 6e38bbc2-8873-472c-a452-8bd4aaea5d3a name: Happy Birthday - theme: Birthday + theme: birthday.html amount: 50 quantity: 1 taxable: false @@ -512,7 +524,7 @@ paths: message: Happy Birthday Jane! created_time: '2018-09-17T14:27:39.000Z' updated_time: '2018-09-17T14:53:40.000Z' - meta: {} + meta: {} '204': description: 'If the action’s result is an empty cart, the cart is automatically deleted.' summary: Delete Cart Line Item @@ -522,7 +534,7 @@ paths: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/cartId' get: - description: Returns a storeʼs *Cart*. + description: Returns a store's *Cart*. parameters: - name: include in: query @@ -549,7 +561,7 @@ paths: operationId: getACart put: description: |- - Updates a *Cartʼs* `customer_id`. + Updates a *Cart's* `customer_id`. **Notes** @@ -784,7 +796,7 @@ paths: $ref: '#/components/schemas/MetafieldResponse' '409': description: | - The `Metafield` conflicts with another `Metafield`. This can be the result of duplicate unique key combinations of the appʼs client id, namespace, key, resource_type, and resource_id. + The `Metafield` conflicts with another `Metafield`. This can be the result of duplicate unique key combinations of the app's client id, namespace, key, resource_type, and resource_id. content: application/json: schema: @@ -811,8 +823,15 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/MetafieldPost' - examples: {} + $ref: '#/components/schemas/MetafieldPost' + example: + { + "permission_set": app_only, + "namespace": Sales Department, + "key": Staff Name, + "value": Sam, + "description": Name of staff member + } description: '' required: true responses: @@ -823,7 +842,19 @@ paths: application/json: schema: $ref: '#/components/schemas/MetaFieldCollectionResponse' - examples: {} + example: + data: + "id": 24 + "key": Staff Name + "value": Sam + "namespace": Sales Department + "permission_set": app_only + "resource_type": cart + "resource_id": b810114d-9926-45b7-bba5-7633b251154b + "description": Name of staff member + "date_created": 2023-11-15T15:16:35+00:00 + "date_modified": 2023-11-15T15:16:35+00:00 + meta: {} '404': description: | The resource was not found. @@ -854,7 +885,7 @@ paths: $ref: '#/components/schemas/MetafieldResponse' '409': description: | - The `Metafield` conflicts with another `Metafield`. This can be the result of duplicate unique key combinations of the appʼs client id, namespace, key, resource_type, and resource_id. + The `Metafield` conflicts with another `Metafield`. This can be the result of duplicate unique key combinations of the app's client id, namespace, key, resource_type, and resource_id. content: application/json: schema: @@ -983,12 +1014,12 @@ components: type: string description: The theme of the gift certificate. enum: - - Birthday - - Boy - - Celebration - - Christmas - - General - - Girl + - birthday.html + - boy.html + - celebration.html + - christmas.html + - general.html + - girl.html amount: type: number minimum: 1 @@ -1047,12 +1078,12 @@ components: type: string description: The theme of the gift certificate. enum: - - Birthday - - Boy - - Celebration - - Christmas - - General - - Girl + - birthday.html + - boy.html + - celebration.html + - christmas.html + - general.html + - girl.html amount: type: number minimum: 1 @@ -1100,8 +1131,10 @@ components: example: usd locale: type: string - description: Accepts string of format `xx` or `xx-YY`. + description: 'The locale of the cart. Accepts strings of format `xx` or `xx-YY`. Uses the [ISO-639 standard](https://www.iso.org/iso-639-language-codes.html) format.' + format: ISO-639 example: en-US + description: '' CartRequestData: type: object title: Cart Request Data @@ -1148,12 +1181,12 @@ components: type: string description: The theme of the gift certificate. enum: - - Birthday - - Boy - - Celebration - - Christmas - - General - - Girl + - birthday.html + - boy.html + - celebration.html + - christmas.html + - general.html + - girl.html amount: type: number minimum: 1 @@ -1253,12 +1286,12 @@ components: type: string description: The theme of the gift certificate. enum: - - Birthday - - Boy - - Celebration - - Christmas - - General - - Girl + - birthday.html + - boy.html + - celebration.html + - christmas.html + - general.html + - girl.html amount: type: number minimum: 1 @@ -1375,7 +1408,8 @@ components: description: 'The channel ID. If no channel is specified, defaults to 1.' locale: type: string - description: Locale of the cart. + description: 'Locale of the cart. Accepts strings of format `xx` or `xx-YY`. Uses the [ISO-639 standard](https://www.iso.org/iso-639-language-codes.html) format.' + format: ISO-639 promotions: type: object description: This is available only when "include=promotions.banners" is presented in the URL. @@ -1450,12 +1484,12 @@ components: type: string description: The theme of the gift certificate. enum: - - Birthday - - Boy - - Celebration - - Christmas - - General - - Girl + - birthday.html + - boy.html + - celebration.html + - christmas.html + - general.html + - girl.html amount: type: number description: 'Value must be between 1.00 and 1,000.00 in the store’s default currency.' @@ -1494,7 +1528,7 @@ components: description: Name provided for the gift certificate that will appear in the control panel. theme: type: string - description: 'The theme of the gift certificate. The following options are available:`Birthday`, `Boy`, `Celebration`, `Christmas`, `General`, and `Girl`.' + description: 'The theme of the gift certificate. The following options are available:`birthday.html`, `boy.html`, `celebration.html`, `christmas.html`, `general.html`, and `girl.html`.' amount: type: number description: 'Value must be between 1.00 and 1,000.00 in the store’s default currency.' @@ -1530,8 +1564,7 @@ components: x-internal: false ItemDigital: allOf: - - type: object - title: Base Item + - title: Base Item properties: id: type: string @@ -1593,8 +1626,6 @@ components: ``` properties: id: - description: ID of the applied discount. - example: coupon oneOf: - type: string - type: number @@ -1684,6 +1715,7 @@ components: type: array items: type: object + title: Product Option properties: name: type: string @@ -1698,13 +1730,11 @@ components: type: number description: The product option value identifier in number format. example: 128 - title: Product Option required: - variant_id - product_id - quantity - - type: object - properties: + - properties: download_file_urls: description: URLs to download all product files. type: array @@ -1718,8 +1748,8 @@ components: download_size: description: 'Specifies the combined download size of all files in human-readable style; for example, `30MB`.' type: string - title: Item Digital - x-internal: false + type: object + title: '' ItemDigitalGet: allOf: - title: Base Item @@ -1784,8 +1814,6 @@ components: ``` properties: id: - description: ID of the applied discount. - example: coupon oneOf: - type: string - type: number @@ -1793,59 +1821,55 @@ components: type: number description: The discounted amount. coupons: - type: array - items: - type: object - title: Applied Coupon - properties: - coupons: + oneOf: + - type: number + - type: array + items: type: object - description: Required in a /POST request. + title: Applied Coupon properties: - coupon_code: - type: object - description: The coupon code. - properties: - id: - type: integer - example: 6 - description: ID of the coupon. - code: - type: string - example: KV56053388J - description: The coupon code. Required in a /POST request. - name: - type: string - example: Percentage off - description: Name given to the coupon in the control panel. - discountType: - type: integer - description: |- - The discount type. - - - type 0: per_item_discount - - type 1: percentage_discount - - type 2: per_total_discount - - type 3: shipping_discount - - type 4: free_shipping - enum: - - 0 - - 1 - - 2 - - 3 - - 4 - discountAmount: - type: integer - description: 'The amount of the discount based on the coupon. For example, 3 percent off will show a 3.' - example: 3 - expiresDate: - type: integer - example: 0 - description: Returns 0 if no expiration date has been set. - totalDiscount: - type: number - example: 4.19 - description: The total amount of all discounts applied to the cart. + id: + type: integer + example: 6 + description: ID of the coupon. + code: + type: string + example: KV56053388J + description: The coupon code. Required in a /POST request. + name: + type: string + example: Percentage off + description: Name given to the coupon in the control panel. + discountType: + type: integer + description: | + The discount type. + - type 0: per_item_discount + - type 1: percentage_discount + - type 2: per_total_discount + - type 3: shipping_discount + - type 4: free_shipping + example: 3 + enum: + - 0 + - 1 + - 2 + - 3 + - 4 + discountAmount: + type: integer + description: 'The amount of the discount based on the coupon. For example, 3 percent off will show a 3.' + example: 3 + expiresDate: + type: integer + example: 0 + description: Returns 0 if no expiration date has been set. + totalDiscount: + type: number + example: 4.19 + description: The total amount of all discounts applied to the cart. + required: + - code discount_amount: type: number description: The total value of all discounts applied to this item. This includes coupons and cart-level discounts. @@ -1902,9 +1926,9 @@ components: download_size: description: 'Specifies the combined download size of all files in human-readable style; for example, `30MB`.' type: string - title: Item Digital - x-internal: false type: object + title: '' + description: '' ItemPhysical: allOf: - type: object @@ -1970,8 +1994,6 @@ components: ``` properties: id: - description: ID of the applied discount. - example: coupon oneOf: - type: string - type: number @@ -2080,22 +2102,8 @@ components: - variant_id - product_id - quantity - - properties: - is_require_shipping: - type: boolean - gift_wrapping: - title: Gift Wrapping - type: object - properties: - name: - type: string - message: - type: string - amount: - type: number - format: float - title: Item Physical - x-internal: false + - {} + description: '' BaseItem: type: object title: Base Item @@ -2118,7 +2126,7 @@ components: description: SKU of the variant. name: type: string - description: The item’s product name. + description: The item's product name. example: T-Shirt url: description: The product URL. @@ -2204,7 +2212,7 @@ components: - type 2: per_total_discount - type 3: shipping_discount - type 4: free_shipping - enum: + enum: - 0 - 1 - 2 @@ -2301,6 +2309,7 @@ components: |`3`|`shipping_discount`| |`4`|`free_shipping`| |`5`|`promotion`| + x-internal: false properties: code: description: The coupon code. @@ -2320,6 +2329,13 @@ components: type 4: free_shipping type 5: promotion type: string + enum: + - '0' + - '1' + - '2' + - '3' + - '4' + - '5' readOnly: true discounted_amount: description: The discounted amount applied within a given context. @@ -2328,7 +2344,6 @@ components: readOnly: true required: - code - x-internal: false AppliedDiscount: type: object title: Applied Discount @@ -2358,7 +2373,7 @@ components: type: object title: Item Custom description: |- - Add a custom item to the shopperʼs cart. + Add a custom item to the shopper's cart. * Custom items are not added to the catalog. * The price should be set to match the store settings for taxes. @@ -2377,12 +2392,12 @@ components: type: string list_price: type: string - description: Specifies the price of the item. This value can include or exclude tax, depending on the store setup. + description: 'Specifies the price of the item. This value can include or exclude tax, depending on the store setup.' ItemCustomGet: type: object title: Item Custom description: |- - Add a custom item to the shopperʼs cart. + Add a custom item to the shopper's cart. * Custom items are not added to the catalog. * The price should be set to match the store settings for taxes. @@ -2401,7 +2416,7 @@ components: type: string list_price: type: string - description: Specifies the price of the item. This value can include or exclude tax, depending on the store setup. + description: 'Specifies the price of the item. This value can include or exclude tax, depending on the store setup.' cart_PostVariant: type: object title: Item with variant @@ -2419,23 +2434,7 @@ components: description: Variant ID. Exists only in Catalog V3. name: type: string - description: Optionally, provide a value to override the product name. - weight: - type: number - description: Optionally, provide a value to override the product weight. - dimensions: - type: object - description: Optionally, provide a value to override the product dimensions. - properties: - height: - type: number - description: The custom height of the product. - width: - type: number - description: The custom width of the product. - depth: - type: number - description: The custom depth of the product. + description: 'Optionally, provide a value to override the product name.' gift_wrapping: type: object properties: @@ -2486,23 +2485,7 @@ components: description: Optional price override. name: type: string - description: Optionally, provide a value to override the product name. - weight: - type: number - description: Optionally, provide a value to override the product weight. - dimensions: - type: object - description: Optionally, provide a value to override the product dimensions. - properties: - height: - type: number - description: The custom height of the product. - width: - type: number - description: The custom width of the product. - depth: - type: number - description: The custom depth of the product. + description: 'Optionally, provide a value to override the product name.' option_selections: type: array description: Needed for Catalog V2. @@ -2563,12 +2546,12 @@ components: type: string description: The theme of the gift certificate. enum: - - Birthday - - Boy - - Celebration - - Christmas - - General - - Girl + - birthday.html + - boy.html + - celebration.html + - christmas.html + - general.html + - girl.html amount: type: number minimum: 1 @@ -2630,12 +2613,12 @@ components: type: string description: The theme of the gift certificate. enum: - - Birthday - - Boy - - Celebration - - Christmas - - General - - Girl + - birthday.html + - boy.html + - celebration.html + - christmas.html + - general.html + - girl.html amount: type: number minimum: 1 @@ -2683,6 +2666,8 @@ components: type: string name: type: string + minLength: 1 + maxLength: 250 quantity: type: number list_price: @@ -2864,8 +2849,6 @@ components: ``` properties: id: - description: ID of the applied discount. - example: coupon oneOf: - type: string - type: number @@ -2873,61 +2856,55 @@ components: type: number description: The discounted amount. coupons: - type: array - items: - type: object - title: Applied Coupon - properties: - coupons: + oneOf: + - type: number + - type: array + items: type: object - description: Required in a /POST request. + title: Applied Coupon properties: - coupon_code: - type: object - description: The coupon code. - properties: - id: - type: integer - example: 6 - description: The ID of the coupon. - code: - type: string - example: KV56053388J - description: The coupon code. Required in a /POST request. - name: - type: string - example: Percentage off - description: Name given to the coupon in the control panel. - discountType: - type: integer - description: |- - The discount type. - - - type 0: per_item_discount - - type 1: percentage_discount - - type 2: per_total_discount - - type 3: shipping_discount - - type 4: free_shipping - enum: - - 0 - - 1 - - 2 - - 3 - - 4 - discountAmount: - type: integer - description: 'The amount of the discount based on the coupon. For example, 3 percent off will show a 3.' - example: 3 - expiresDate: - type: integer - example: 0 - description: Returns 0 if no expiration date is set. - totalDiscount: - type: number - example: 4.19 - description: The total amount of all discounts applied to the cart. + id: + type: integer + example: 6 + description: ID of the coupon. + code: + type: string + example: KV56053388J + description: The coupon code. Required in a /POST request. + name: + type: string + example: Percentage off + description: Name given to the coupon in the control panel. + discountType: + type: integer + description: |- + The discount type. + - type 0: per_item_discount + - type 1: percentage_discount + - type 2: per_total_discount + - type 3: shipping_discount + - type 4: free_shipping + example: 3 + enum: + - 0 + - 1 + - 2 + - 3 + - 4 + discountAmount: + type: integer + description: 'The amount of the discount based on the coupon. For example, 3 percent off will show a 3.' + example: 3 + expiresDate: + type: integer + example: 0 + description: Returns 0 if no expiration date has been set. + totalDiscount: + type: number + example: 4.19 + description: The total amount of all discounts applied to the cart. required: - - coupon_code + - code discount_amount: type: number description: The total value of all discounts applied to this item. This includes coupons and cart-level discounts. @@ -2961,35 +2938,41 @@ components: type: string description: 'The product option name; for example, Color or Size.' nameId: - type: number + type: number + example: 151 description: The product option identifier. value: type: string description: 'The product option value; for example, Red or Medium.' valueId: - type: number + oneOf: + - type: number + example: 128 + - type: string + example: "1259" description: The product option value identifier in number format. - example: 128 - required: - - variant_id - - product_id - - quantity - - properties: - is_require_shipping: - type: boolean + gift_wrapping: - title: Gift Wrapping + description: The gift wrapping details for this item. type: object properties: name: type: string + example: Gift Wrap 1 message: type: string + example: Happy Birthday! amount: type: number format: float - title: Item Physical Get - x-internal: false + example: 1.99 + required: + - variant_id + - product_id + - quantity + - {} + title: '' + description: '' NotFound: description: Error payload for the BigCommerce API. type: object @@ -3030,7 +3013,7 @@ components: date_created: type: string format: date-time - description: Date and time of the metafieldʼs creation. + description: Date and time of the metafield's creation. example: '2022-06-16T18:39:00+00:00' date_modified: type: string @@ -3048,7 +3031,6 @@ components: type: string description: | Determines the visibility and writeability of the field by other API consumers. - | Value | Description | | :--- | :--- | | `app_only` | Private to the app that owns the field. | @@ -3125,7 +3107,6 @@ components: type: string description: | Determines the visibility and writeability of the field by other API consumers. - | Value | Description | | :--- | :--- | | `app_only` | Private to the app that owns the field. | @@ -3178,9 +3159,7 @@ components: Response payload for the BigCommerce API. properties: data: - type: array - items: - $ref: '#/components/schemas/Metafield' + $ref: '#/components/schemas/Metafield' meta: $ref: '#/components/schemas/CollectionMeta' x-internal: false @@ -3252,6 +3231,7 @@ components: application/json: schema: $ref: '#/components/schemas/Cart_Full' + examples: {} CartRedirectResponse: description: '' content: @@ -3298,10 +3278,9 @@ components: name: Content-Type in: header required: true - description: 'The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the request body.' schema: type: string - default: 'application/json' + default: application/json cartId: name: cartId in: path @@ -3351,14 +3330,14 @@ components: MetafieldKeyParam: name: key in: query - description: Filter based on a metafieldʼs key. + description: Filter based on a metafield's key. required: false schema: type: string MetafieldNamespaceParam: name: namespace in: query - description: Filter based on a metafieldʼs key. + description: Filter based on a metafield's key. required: false schema: type: string @@ -3396,14 +3375,14 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header diff --git a/reference/catalog.v3.yml b/reference/catalog.v3.yml deleted file mode 100644 index 67d6c6e4d..000000000 --- a/reference/catalog.v3.yml +++ /dev/null @@ -1,27591 +0,0 @@ -openapi: '3.0.3' -info: - title: Catalog - description: |- - The Catalog API allows you to manage products, categories, bulk pricing rules, and more. To learn more about catalog resources see [Catalog Overview](/api-docs/store-management/catalog/catalog-overview). - - - [Authentication](#authentication) - - [Resources](#resources) - - ## Resources - - ### Webhooks - * [Category](/api-docs/store-management/webhooks/events#category) - - ### Related Endpoints - * [Catalog API](/docs/rest-management/catalog) - - Manage channel-specific categories. - - Create and manage category trees for BigCommerce stores. - - Create and manage products assignments. - termsOfService: 'https://www.bigcommerce.com/terms' - contact: - name: BigCommerce - url: 'https://www.bigcommerce.com' - email: support@bigcommerce.com - version: '' -servers: - - url: 'https://api.bigcommerce.com/stores/{store_hash}/v3' - variables: - store_hash: - default: store_hash - description: Permanent ID of the BigCommerce store. - description: BigCommerce API Gateway -security: - - X-Auth-Token: [] -tags: - - name: Brands - - name: Brand Images - - name: Brand Metafields - - name: Category - - name: Categories - - name: Categories Batch - - name: Category Metafields - - name: Category Images - - name: Product Sort Order - - name: Products - - name: Product Bulk Pricing Rules - - name: Product Complex Rules - - name: Product Custom Fields - - name: Product Images - - name: Product Metafields - - name: Product Modifiers - - name: Product Modifier Values - - name: Product Modifier Images - - name: Product Options - - name: Product Option Values - - name: Product Reviews - - name: Product Variants - - name: Product Variants Metafields - - name: Product Variant Options - - name: Product Variant Option Values - - name: Product Videos - - name: Products Channel Assignments - - name: Products Category Assignments - - name: Summary - - name: Variants - - name: Category Trees -paths: - '/catalog/products': - get: - tags: - - Products - summary: Get All Products - description: Returns a list of **Products**. Optional filter parameters can be passed in. - operationId: getProducts - parameters: - - name: id - in: query - description: | - Filter items by id. - schema: - type: integer - - name: 'id:in' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: 'id:not_in' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: 'id:min' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: 'id:max' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: 'id:greater' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: 'id:less' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: name - in: query - description: | - Filter items by name. - schema: - type: string - - name: upc - in: query - description: | - Filter items by upc. - schema: - type: string - - name: price - in: query - description: | - Filter items by price. - schema: - type: number - - name: weight - in: query - description: | - Filter items by weight. - schema: - type: number - - name: condition - in: query - description: | - Filter items by condition. - schema: - type: string - enum: - - new - - used - - refurbished - - name: brand_id - in: query - description: | - Filter items by brand_id. - schema: - type: integer - - name: date_modified - in: query - description: 'Filter items by `date_modified`. ' - schema: - type: string - format: date-time - - name: 'date_modified:max' - in: query - description: 'Filter items by `date_modified`. For example, `date_modified:max=2020-06-15`.' - schema: - type: string - - name: 'date_modified:min' - in: query - description: 'Filter items by `date_modified`. For example, `date_modified:min=2018-06-15`.' - schema: - type: string - - name: date_last_imported - in: query - description: Filter items by date_last_imported. - schema: - type: string - format: date-time - - name: 'date_last_imported:max' - in: query - description: 'Filter items by date_last_imported. For example, `date_last_imported:max=2020-06-15`.' - schema: - type: string - - name: 'date_last_imported:min' - in: query - description: 'Filter items by date_last_imported. For example, `date_last_imported:min=2018-06-15`.' - schema: - type: string - - name: is_visible - in: query - description: Filter items based on whether the product is currently visible on the storefront. - schema: - type: boolean - - name: is_featured - in: query - description: 'Filter items by is_featured. `1` for true, `0` for false.' - schema: - type: integer - enum: - - 1 - - 0 - - name: is_free_shipping - in: query - description: 'Filter items by is_free_shipping. `1` for true, `0` for false.' - schema: - type: integer - - name: inventory_level - in: query - description: | - Filter items by inventory_level. - schema: - type: integer - - name: 'inventory_level:in' - in: query - schema: - type: integer - - name: 'inventory_level:not_in' - in: query - schema: - type: integer - - name: 'inventory_level:min' - in: query - schema: - type: integer - - name: 'inventory_level:max' - in: query - schema: - type: integer - - name: 'inventory_level:greater' - in: query - schema: - type: integer - - name: 'inventory_level:less' - in: query - schema: - type: integer - - name: inventory_low - in: query - description: | - Filter items by inventory_low. Values: 1, 0. - schema: - type: integer - - name: out_of_stock - in: query - description: | - Filter items by out_of_stock. To enable the filter, pass `out_of_stock`=`1`. - schema: - type: integer - - name: total_sold - in: query - description: | - Filter items by total_sold. - schema: - type: integer - - name: type - in: query - description: Filter items by type. - schema: - type: string - enum: - - digital - - physical - - name: categories - in: query - description: |- - Filter items by categories. - If a product is in more than one category, using this query will not return the product. Instead use `categories:in=12`. - schema: - type: integer - - name: keyword - in: query - description: Filter items by keywords found in the `name` or `sku` fields - schema: - type: string - - name: keyword_context - in: query - description: Set context used by the search algorithm to return results targeted towards the specified group. Use `merchant` to help merchants search their own catalog. Use `shopper` to return shopper-facing search results. - schema: - type: string - enum: - - shopper - - merchant - - name: status - in: query - description: | - Filter items by status. - schema: - type: integer - - name: include - in: query - description: 'Sub-resources to include on a product, in a comma-separated list. If `options` or `modifiers` is used, results are limited to 10 per page.' - schema: - type: string - enum: - - variants - - images - - custom_fields - - bulk_pricing_rules - - primary_image - - modifiers - - options - - videos - - name: include_fields - in: query - description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' - schema: - type: string - - name: exclude_fields - in: query - description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' - schema: - type: string - - name: availability - in: query - description: | - Filter items by availability. Values are: available, disabled, preorder. - schema: - type: string - enum: - - available - - disabled - - preorder - - name: page - in: query - description: Specifies the page number in a limited (paginated) list of products. - schema: - type: integer - - name: limit - in: query - description: Controls the number of items per page in a limited (paginated) list of products. - schema: - type: integer - - name: direction - in: query - description: | - Sort direction. Acceptable values are: `asc`, `desc`. - schema: - type: string - enum: - - asc - - desc - - name: sort - in: query - description: | - Field name to sort by. Note: Since `id` increments when new products are added, you can use that field to sort by product create date. - schema: - type: string - enum: - - id - - name - - sku - - price - - date_modified - - date_last_imported - - inventory_level - - is_visible - - total_sold - - name: 'categories:in' - in: query - description: 'Filter items by categories. Use for products in multiple categories. For example, `categories:in=12`.' - schema: - type: integer - - name: sku - in: query - description: 'Filter items by main SKU. To filter by variant SKU, see [Get All Variants](/docs/rest-management/catalog/product-variants#get-all-product-variants). ' - schema: - type: string - - name: 'sku:in' - in: query - description: Filter items by SKU. - style: form - explode: false - schema: - type: array - items: - type: string - responses: - '200': - description: '' - content: - application/json: - schema: - type: object - properties: - data: - type: array - items: - $ref: '#/components/schemas/product_Full' - meta: - $ref: '#/components/schemas/metaCollection_Full' - put: - tags: - - Products - summary: Update Products (Batch) - description: |- - Updates products in batches. Batches are limited to 10 products. - - **Required Fields** - * `id` - product `id` is required for batch updates to products. - - **Read-Only Fields** - - `id` - - `date_created` - - `date_modified` - - `calculated_price` - - `base_variant_id` - operationId: updateProducts - parameters: - - $ref: '#/components/parameters/ContentType' - - name: include_fields - in: query - description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/product_Put_Collection' - examples: - example-1: - value: - - name: Smith Journal 13 - type: physical - sku: SM-13 - description: '<p><span>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vel metus ac est egestas porta sed quis erat. Integer id nulla massa. Proin vitae enim nisi. Praesent non dignissim nulla. Nulla mattis id massa ac pharetra. Mauris et nisi in dolor aliquam sodales. Aliquam dui nisl, dictum quis leo sit amet, rutrum volutpat metus. Curabitur libero nunc, interdum ac libero non, tristique porttitor metus. Ut non dignissim lorem, in vestibulum leo. Vivamus sodales quis turpis eget.</span></p>' - weight: 0 - width: 0 - depth: 0 - height: 0 - price: 0 - cost_price: 0 - retail_price: 0 - sale_price: 0 - map_price: 0 - tax_class_id: 0 - product_tax_code: string - categories: - - 0 - brand_id: 0 - inventory_level: 0 - inventory_warning_level: 0 - inventory_tracking: none - fixed_cost_shipping_price: 0 - is_free_shipping: true - is_visible: true - is_featured: true - related_products: - - 0 - warranty: string - bin_picking_number: string - layout_file: string - upc: string - search_keywords: string - availability: available - availability_description: string - gift_wrapping_options_type: any - gift_wrapping_options_list: - - 0 - sort_order: -2147483648 - condition: New - is_condition_shown: true - order_quantity_minimum: 0 - order_quantity_maximum: 0 - page_title: string - meta_keywords: - - string - meta_description: string - view_count: 0 - preorder_release_date: '2019-08-24T14:15:22Z' - preorder_message: string - is_preorder_only: true - is_price_hidden: true - price_hidden_label: string - custom_url: - url: string - is_customized: true - open_graph_type: product - open_graph_title: string - open_graph_description: string - open_graph_use_meta_description: true - open_graph_use_product_name: true - open_graph_use_image: true - brand_name or brand_id: Common Good - gtin: string - mpn: string - reviews_rating_sum: 3 - reviews_count: 4 - total_sold: 80 - custom_fields: - - id: 6 - name: ISBN - value: '1234567890123' - bulk_pricing_rules: - - id: 0 - quantity_min: 10 - quantity_max: 50 - type: price - amount: 10 - images: - - image_file: string - is_thumbnail: true - sort_order: -2147483648 - description: string - image_url: string - id: 0 - product_id: 0 - url_zoom: string - url_standard: string - url_thumbnail: string - url_tiny: string - date_modified: '2019-08-24T14:15:22Z' - videos: - - title: Writing Great Documentation - description: A video about documenation - sort_order: 1 - type: youtube - video_id: z3fRu9pkuXE - id: 0 - product_id: 0 - length: string - required: false - responses: - '200': - description: '' - content: - application/json: - schema: - type: object - properties: - data: - type: array - items: - $ref: '#/components/schemas/product_Full' - meta: - $ref: '#/components/schemas/metaCollection_Full' - examples: - example-1: - value: - data: - - id: 1 - name: Smith Journal 13 - type: physical - sku: SM-13 - description: '<p><span>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vel metus ac est egestas porta sed quis erat. Integer id nulla massa. Proin vitae enim nisi. Praesent non dignissim nulla. Nulla mattis id massa ac pharetra. Mauris et nisi in dolor aliquam sodales. Aliquam dui nisl, dictum quis leo sit amet, rutrum volutpat metus. Curabitur libero nunc, interdum ac libero non, tristique porttitor metus. Ut non dignissim lorem, in vestibulum leo. Vivamus sodales quis turpis eget.</span></p>' - weight: 0 - width: 0 - depth: 0 - height: 0 - price: 0 - cost_price: 0 - retail_price: 0 - sale_price: 0 - map_price: 0 - tax_class_id: 0 - product_tax_code: string - categories: - - 0 - brand_id: 0 - inventory_level: 0 - inventory_warning_level: 0 - inventory_tracking: none - fixed_cost_shipping_price: 0 - is_free_shipping: true - is_visible: true - is_featured: true - related_products: - - 0 - warranty: string - bin_picking_number: string - layout_file: string - upc: string - search_keywords: string - availability: available - availability_description: string - gift_wrapping_options_type: any - gift_wrapping_options_list: - - 0 - sort_order: -2147483648 - condition: New - is_condition_shown: true - order_quantity_minimum: 0 - order_quantity_maximum: 0 - page_title: string - meta_keywords: - - string - meta_description: string - view_count: 0 - preorder_release_date: '2019-08-24T14:15:22Z' - preorder_message: string - is_preorder_only: true - is_price_hidden: true - price_hidden_label: string - custom_url: - url: string - is_customized: true - open_graph_type: product - open_graph_title: string - open_graph_description: string - open_graph_use_meta_description: true - open_graph_use_product_name: true - open_graph_use_image: true - brand_name or brand_id: Common Good - gtin: string - mpn: string - reviews_rating_sum: 3 - reviews_count: 4 - total_sold: 80 - custom_fields: - - id: 6 - name: ISBN - value: '1234567890123' - bulk_pricing_rules: - - id: 0 - quantity_min: 10 - quantity_max: 50 - type: price - amount: 10 - images: - - image_file: string - is_thumbnail: true - sort_order: -2147483648 - description: string - image_url: string - id: 0 - product_id: 0 - url_zoom: string - url_standard: string - url_thumbnail: string - url_tiny: string - date_modified: '2019-08-24T14:15:22Z' - videos: - - title: Writing Great Documentation - description: A video about documenation - sort_order: 1 - type: youtube - video_id: z3fRu9pkuXE - id: 0 - product_id: 0 - length: string - date_created: '2018-08-15T14:49:05+00:00' - date_modified: '2018-08-24T14:41:00+00:00' - base_variant_id: 0 - calculated_price: 0 - options: - - id: 55 - product_id: 4 - display_name: Add-a-$5-Donation1535042499-187 - type: radio_buttons - config: - default_value: string - checked_by_default: true - checkbox_label: string - date_limited: true - date_limit_mode: range - date_earliest_value: '2019-08-24' - date_latest_value: '2019-08-24' - file_types_mode: specific - file_types_supported: - - 'images, documents, other' - file_types_other: - - pdf - file_max_size: 5 - text_characters_limited: true - text_min_length: 1 - text_max_length: 55 - text_lines_limited: true - text_max_lines: 4 - number_limited: true - number_limit_mode: lowest - number_lowest_value: 100 - number_highest_value: 0 - number_integers_only: false - product_list_adjusts_inventory: true - product_list_adjusts_pricing: true - product_list_shipping_calc: weight - sort_order: 1 - option_values: - is_default: false - label: Green - sort_order: 0 - value_data: {} - id: 0 - modifiers: - - type: date - required: true - sort_order: 0 - config: - default_value: string - checked_by_default: true - checkbox_label: string - date_limited: true - date_limit_mode: range - date_earliest_value: '2019-08-24' - date_latest_value: '2019-08-24' - file_types_mode: specific - file_types_supported: - - 'images, documents, other' - file_types_other: - - pdf - file_max_size: 5 - text_characters_limited: true - text_min_length: 1 - text_max_length: 55 - text_lines_limited: true - text_max_lines: 4 - number_limited: true - number_limit_mode: lowest - number_lowest_value: 100 - number_highest_value: 0 - number_integers_only: false - product_list_adjusts_inventory: true - product_list_adjusts_pricing: true - product_list_shipping_calc: weight - display_name: string - id: 12 - product_id: 77 - name: Add-a-$5-Donation1535039590-191 - option_values: - - is_default: false - label: Green - sort_order: 0 - value_data: {} - adjusters: - price: - adjuster: relative - adjuster_value: 5 - weight: - adjuster: relative - adjuster_value: 5 - image_url: 'https://cdn8.bigcommerce.com/s-{{store_hash}}/products/184/images/445/naturalcanvascart2_1024x1024__92347__29648.1534344533.1280.1280.jpg?c=2' - purchasing_disabled: - status: true - message: string - id: 0 - option_id: 0 - option_set_id: 0 - option_set_display: string - variants: - - cost_price: 0 - price: 0 - sale_price: 0 - retail_price: 0 - weight: 0 - width: 0 - height: 0 - depth: 0 - is_free_shipping: true - fixed_cost_shipping_price: 0 - purchasing_disabled: true - purchasing_disabled_message: string - upc: string - inventory_level: 0 - inventory_warning_level: 0 - bin_picking_number: string - mpn: string - gtin: '012345678905' - id: 0 - product_id: 0 - sku: string - sku_id: 0 - option_values: - - option_display_name: Color - label: Beige - id: 146 - option_id: 151 - calculated_price: 0 - calculated_weight: 0 - meta: - pagination: - total: 36 - count: 36 - per_page: 50 - current_page: 1 - total_pages: 1 - links: - previous: string - current: '?page=1&limit=50' - next: string - '207': - description: |- - Multi-status. The product information was updated successfully, but the inventory data failed to update. - - Verify that the inventory-related updates are well-formed and correct; for example, that they donʼt result in negative stock levels. Then consider updating the inventory data again. - content: - application/json: - schema: - type: object - properties: - data: - type: array - items: - $ref: '#/components/schemas/product_Full' - errors: - $ref: '#/components/schemas/errorMultiStatus' - meta: - $ref: '#/components/schemas/metaCollection_Full' - '404': - description: The resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - '409': - description: '`Product` was in conflict with another product. This is the result of duplicate unique values such as name or SKU; a missing or invalid `category_id`, `brand_id`, or `tax_class id`; or a conflicting `bulk_pricing_rule`.' - content: - application/json: - schema: - $ref: '#/components/schemas/errorResponse_409' - '413': - description: 413 Request Entity Too Large - content: - application/json: - schema: - $ref: '#/components/schemas/error_Base' - example: - errors: {} - status: 413 - title: The request payload is too large. The maximum items allowed in the array is 50 - type: /api-docs/getting-started/api-status-codes - '422': - description: '`Product` was not valid. This is the result of missing required fields or invalid data. See the response for more details.' - content: - application/json: - schema: - $ref: '#/components/schemas/errorResponse_422' - x-codegen-request-body-name: products - post: - tags: - - Products - summary: Create a Product - description: |- - Creates a *Product*. Only one product can be created at a time. - - **Required Fields:** - - `name` - - `type` - - `weight` - - `price` - - **Read-Only Fields** - - `id` - - `date_created` - - `date_modified` - - `calculated_price` - - `base_variant_id` - - **Limits** - - 250 characters product name length. - - **Usage Notes** - * `POST` requests to `/products` accept a `video` array. - * `POST` requests to `/products/{product_id}/videos` accept a `video` object. - operationId: createProduct - parameters: - - $ref: '#/components/parameters/ContentType' - - name: include_fields - in: query - description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/product_Base' - required: true - responses: - '200': - description: '' - content: - application/json: - schema: - title: Product Response - type: object - properties: - data: - $ref: '#/components/schemas/product_Full' - meta: - $ref: '#/components/schemas/metaEmpty_Full' - example-1: - example: - name: Smith Journal 13 - type: physical - sku: SM-13 - description: '<p><span>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vel metus ac est egestas porta sed quis erat. Integer id nulla massa. Proin vitae enim nisi. Praesent non dignissim nulla. Nulla mattis id massa ac pharetra. Mauris et nisi in dolor aliquam sodales. Aliquam dui nisl, dictum quis leo sit amet, rutrum volutpat metus. Curabitur libero nunc, interdum ac libero non, tristique porttitor metus. Ut non dignissim lorem, in vestibulum leo. Vivamus sodales quis turpis eget.</span></p>' - weight: 0 - width: 0 - depth: 0 - height: 0 - price: 0 - cost_price: 0 - retail_price: 0 - sale_price: 0 - map_price: 0 - tax_class_id: 0 - product_tax_code: string - categories: - - 0 - brand_id: 0 - inventory_level: 0 - inventory_warning_level: 0 - inventory_tracking: none - fixed_cost_shipping_price: 0 - is_free_shipping: true - is_visible: true - is_featured: true - related_products: - - 0 - warranty: string - bin_picking_number: string - layout_file: string - upc: string - search_keywords: string - availability: available - availability_description: string - gift_wrapping_options_type: any - gift_wrapping_options_list: - - 0 - sort_order: -2147483648 - condition: New - is_condition_shown: true - order_quantity_minimum: 0 - order_quantity_maximum: 0 - page_title: string - meta_keywords: - - string - meta_description: string - view_count: 0 - preorder_release_date: '2019-08-24T14:15:22+00:00' - preorder_message: string - is_preorder_only: true - is_price_hidden: true - price_hidden_label: string - custom_url: - url: string - is_customized: true - open_graph_type: product - open_graph_title: string - open_graph_description: string - open_graph_use_meta_description: true - open_graph_use_product_name: true - open_graph_use_image: true - brand_name or brand_id: Common Good - gtin: string - mpn: string - reviews_rating_sum: 3.2 - reviews_count: 4 - total_sold: 80 - custom_fields: - - id: 6 - name: ISBN - value: '1234567890123' - bulk_pricing_rules: - - id: 0 - quantity_min: 10 - quantity_max: 50 - type: price - amount: 10 - images: - - image_file: string - is_thumbnail: true - sort_order: -2147483648 - description: string - image_url: string - id: 0 - product_id: 0 - url_zoom: string - url_standard: string - url_thumbnail: string - url_tiny: string - date_modified: '2019-08-24T14:15:22+00:00' - videos: - - title: string - description: string - sort_order: -2147483648 - type: youtube - video_id: string - id: 0 - product_id: 0 - length: string - date_created: '2018-08-15T14:49:05+00:00' - date_modified: '2018-08-24T14:41:00+00:00' - id: 1 - base_variant_id: 0 - calculated_price: 0 - options: - - id: 55 - product_id: 4 - display_name: Add-a-$5-Donation1535042499-187 - type: radio_buttons - config: - default_value: string - checked_by_default: true - checkbox_label: string - date_limited: true - date_limit_mode: range - date_earliest_value: '2019-08-24T00:00:00+00:00' - date_latest_value: '2019-08-24T00:00:00+00:00' - file_types_mode: specific - file_types_supported: - - 'images, documents, other' - file_types_other: - - pdf - file_max_size: 5 - text_characters_limited: true - text_min_length: 1 - text_max_length: 55 - text_lines_limited: true - text_max_lines: 4 - number_limited: true - number_limit_mode: lowest - number_lowest_value: 100 - number_highest_value: 0 - number_integers_only: false - product_list_adjusts_inventory: true - product_list_adjusts_pricing: true - product_list_shipping_calc: weight - sort_order: 1 - option_values: - is_default: false - label: Green - sort_order: 0 - value_data: {} - id: 0 - modifiers: - - type: date - required: true - sort_order: 0 - config: - default_value: string - checked_by_default: true - checkbox_label: string - date_limited: true - date_limit_mode: range - date_earliest_value: '2019-08-24T00:00:00+00:00' - date_latest_value: '2019-08-24T00:00:00+00:00' - file_types_mode: specific - file_types_supported: - - 'images, documents, other' - file_types_other: - - pdf - file_max_size: 5 - text_characters_limited: true - text_min_length: 1 - text_max_length: 55 - text_lines_limited: true - text_max_lines: 4 - number_limited: true - number_limit_mode: lowest - number_lowest_value: 100 - number_highest_value: 0 - number_integers_only: false - product_list_adjusts_inventory: true - product_list_adjusts_pricing: true - product_list_shipping_calc: weight - display_name: string - id: 12 - product_id: 77 - name: Add-a-$5-Donation1535039590-191 - option_values: - - is_default: false - label: Green - sort_order: 0 - value_data: {} - adjusters: - price: - adjuster: relative - adjuster_value: 5 - weight: - adjuster: relative - adjuster_value: 5 - image_url: 'https://cdn8.bigcommerce.com/s-{{store_hash}}/products/184/images/445/naturalcanvascart2_1024x1024__92347__29648.1534344533.1280.1280.jpg?c=2' - purchasing_disabled: - status: true - message: string - id: 0 - option_id: 0 - option_set_id: 0 - option_set_display: string - variants: - - cost_price: 0 - price: 0 - sale_price: 0 - retail_price: 0 - weight: 0 - width: 0 - height: 0 - depth: 0 - is_free_shipping: true - fixed_cost_shipping_price: 0 - purchasing_disabled: true - purchasing_disabled_message: string - upc: string - inventory_level: 0 - inventory_warning_level: 0 - bin_picking_number: string - mpn: string - gtin: '012345678905' - id: 0 - product_id: 0 - sku: string - sku_id: 0 - option_values: - - option_display_name: Color - label: Beige - id: 146 - option_id: 151 - calculated_price: 0 - calculated_weight: 0 - meta: {} - '207': - '207': - description: |- - Multi-status. The product information was updated successfully, but the inventory data failed to update. - - Verify that the inventory-related updates are well-formed and correct; for example, that they donʼt result in negative stock levels. Then consider updating the inventory data again. - content: - application/json: - schema: - type: object - properties: - data: - type: array - items: - $ref: '#/components/schemas/product_Full' - errors: - $ref: '#/components/schemas/errorMultiStatus' - meta: - $ref: '#/components/schemas/metaCollection_Full' - - '409': - description: | - `Product` was in conflict with another product. This is the result of duplicate unique values, such as name or SKU; a missing or invalid `category_id`, `brand_id`, or `tax_class id`; or a conflicting `bulk_pricing_rule`. - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - '422': - description: | - `Product` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - x-codegen-request-body-name: product - delete: - tags: - - Products - summary: Delete Products - description: |- - To delete *Product* objects, you must include a filter. This prevents inadvertently deleting all *Product* objects in a store. - - > #### Note - > The maximum number of products you can delete at one time is 250. - - **Example**: - To delete products with the id's of 1,2 and 3, use `DELETE /v3/catalog/products?id:in=1,2,3`. - operationId: deleteProducts - parameters: - - name: name - in: query - description: | - Filter items by name. - schema: - type: string - - name: sku - in: query - description: | - Filter items by sku. - schema: - type: string - - name: price - in: query - description: | - Filter items by price. - schema: - type: number - - name: weight - in: query - description: | - Filter items by weight. - schema: - type: number - - name: condition - in: query - description: | - Filter items by condition. - schema: - type: string - enum: - - new - - used - - refurbished - - name: brand_id - in: query - description: | - Filter items by brand_id. - schema: - type: integer - - name: date_modified - in: query - description: 'Filter items by date_modified. For example `v3/catalog/products?date_modified:min=2018-06-15`' - schema: - type: string - format: date-time - - name: date_last_imported - in: query - description: 'Filter items by date_last_imported. For example `v3/catalog/products?date_last_imported:min=2018-06-15`' - schema: - type: string - format: date-time - - name: is_visible - in: query - description: 'Filter items by if visible on the storefront. ' - schema: - type: boolean - - name: is_featured - in: query - description: | - Filter items by is_featured. - schema: - type: integer - - name: inventory_level - in: query - description: | - Filter items by inventory_level. - schema: - type: integer - - name: total_sold - in: query - description: | - Filter items by total_sold. - schema: - type: integer - - name: type - in: query - description: 'Filter items by type: `physical` or `digital`.' - schema: - type: string - enum: - - digital - - physical - - name: categories - in: query - description: |- - Filter items by categories. - If a product is in more than one category, using this query will not return the product. Instead use `categories:in=12`. - schema: - type: integer - - name: keyword - in: query - description: | - Filter items by keywords found in the `name`, `description`, or `sku` fields, or in the brand name. - schema: - type: string - responses: - '204': - description: '' - content: {} - parameters: - - $ref: '#/components/parameters/Accept' - '/catalog/products/{product_id}': - get: - tags: - - Products - summary: Get a Product - description: Returns a single *Product*. Optional parameters can be passed in. - operationId: getProductById - parameters: - - name: include - in: query - description: 'Sub-resources to include on a product, in a comma-separated list. If `options` or `modifiers` is used, results are limited to 10 per page.' - schema: - type: string - enum: - - variants - - images - - custom_fields - - bulk_pricing_rules - - primary_image - - modifiers - - options - - videos - - name: include_fields - in: query - description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' - schema: - type: string - - name: exclude_fields - in: query - description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' - schema: - type: string - responses: - '200': - description: '' - content: - application/json: - schema: - title: Product Response - type: object - properties: - data: - $ref: '#/components/schemas/product_Full' - meta: - $ref: '#/components/schemas/metaEmpty_Full' - example: - data: - id: 174 - name: 1L Le Parfait Jar - type: physical - sku: '' - description: '<p><span>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vel metus ac est egestas porta sed quis erat. Integer id nulla massa. Proin vitae enim nisi. Praesent non dignissim nulla. Nulla mattis id massa ac pharetra. Mauris et nisi in dolor aliquam sodales. Aliquam dui nisl, dictum quis leo sit amet, rutrum volutpat metus. Curabitur libero nunc, interdum ac libero non, tristique porttitor metus. Ut non dignissim lorem, in vestibulum leo. Vivamus sodales quis turpis eget.</span></p>' - weight: 1 - width: 0 - depth: 0 - height: 0 - price: 7.95 - cost_price: 0 - retail_price: 10 - sale_price: 0 - map_price: 0 - tax_class_id: 0 - product_tax_code: '' - calculated_price: 7.95 - categories: - - 23 - - 21 - brand_id: 36 - option_set_id: 55 - option_set_display: right - inventory_level: 0 - inventory_warning_level: 0 - inventory_tracking: none - reviews_rating_sum: 0 - reviews_count: 0 - total_sold: 7 - fixed_cost_shipping_price: 0 - is_free_shipping: false - is_visible: true - is_featured: false - related_products: - - -1 - warranty: '' - bin_picking_number: '' - layout_file: product.html - upc: '' - mpn: '' - gtin: '' - search_keywords: 'jar, glass' - availability: available - availability_description: '' - gift_wrapping_options_type: any - gift_wrapping_options_list: [] - sort_order: 0 - condition: New - is_condition_shown: false - order_quantity_minimum: 0 - order_quantity_maximum: 0 - page_title: '' - meta_keywords: [] - meta_description: '' - date_created: '2018-08-15T14:48:46+00:00' - date_modified: '2018-09-05T20:42:07+00:00' - view_count: 10 - preorder_release_date: '2018-09-05T20:42:07+00:00' - preorder_message: '' - is_preorder_only: false - is_price_hidden: false - price_hidden_label: '' - custom_url: - url: /all/1l-le-parfait-jar/ - is_customized: true - base_variant_id: 345 - open_graph_type: product - open_graph_title: '' - open_graph_description: '' - open_graph_use_meta_description: true - open_graph_use_product_name: true - open_graph_use_image: true - meta: {} - '404': - description: | - The resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - put: - tags: - - Products - summary: Update a Product - description: | - Updates a *Product*. - - **Read-Only Fields** - - id - - date_created - - date_modified - - calculated_price - - base_variant_id - operationId: updateProduct - parameters: - - $ref: '#/components/parameters/ContentType' - - name: include_fields - in: query - description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' - schema: - type: string - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/product_Put' - required: true - responses: - '200': - description: '' - content: - application/json: - schema: - title: Product Response - type: object - properties: - data: - $ref: '#/components/schemas/product_Full' - meta: - $ref: '#/components/schemas/metaEmpty_Full' - example-1: - example: - name: Smith Journal 13 - type: physical - sku: SM-13 - description: '<p><span>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vel metus ac est egestas porta sed quis erat. Integer id nulla massa. Proin vitae enim nisi. Praesent non dignissim nulla. Nulla mattis id massa ac pharetra. Mauris et nisi in dolor aliquam sodales. Aliquam dui nisl, dictum quis leo sit amet, rutrum volutpat metus. Curabitur libero nunc, interdum ac libero non, tristique porttitor metus. Ut non dignissim lorem, in vestibulum leo. Vivamus sodales quis turpis eget.</span></p>' - weight: 0 - width: 0 - depth: 0 - height: 0 - price: 0 - cost_price: 0 - retail_price: 0 - sale_price: 0 - map_price: 0 - tax_class_id: 0 - product_tax_code: string - categories: - - 0 - brand_id: 0 - inventory_level: 0 - inventory_warning_level: 0 - inventory_tracking: none - fixed_cost_shipping_price: 0 - is_free_shipping: true - is_visible: true - is_featured: true - related_products: - - 0 - warranty: string - bin_picking_number: string - layout_file: string - upc: string - search_keywords: string - availability: available - availability_description: string - gift_wrapping_options_type: any - gift_wrapping_options_list: - - 0 - sort_order: -2147483648 - condition: New - is_condition_shown: true - order_quantity_minimum: 0 - order_quantity_maximum: 0 - page_title: string - meta_keywords: - - string - meta_description: string - view_count: 0 - preorder_release_date: '2019-08-24T14:15:22+00:00' - preorder_message: string - is_preorder_only: true - is_price_hidden: true - price_hidden_label: string - custom_url: - url: string - is_customized: true - open_graph_type: product - open_graph_title: string - open_graph_description: string - open_graph_use_meta_description: true - open_graph_use_product_name: true - open_graph_use_image: true - brand_name or brand_id: Common Good - gtin: string - mpn: string - reviews_rating_sum: 3.2 - reviews_count: 4 - total_sold: 80 - custom_fields: - - id: 6 - name: ISBN - value: '1234567890123' - bulk_pricing_rules: - - id: 0 - quantity_min: 10 - quantity_max: 50 - type: price - amount: 10 - images: - - image_file: string - is_thumbnail: true - sort_order: -2147483648 - description: string - image_url: string - id: 0 - product_id: 0 - url_zoom: string - url_standard: string - url_thumbnail: string - url_tiny: string - date_modified: '2019-08-24T14:15:22+00:00' - videos: - - title: string - description: string - sort_order: -2147483648 - type: youtube - video_id: string - id: 0 - product_id: 0 - length: string - date_created: '2018-08-15T14:49:05+00:00' - date_modified: '2018-08-24T14:41:00+00:00' - id: 1 - base_variant_id: 0 - calculated_price: 0 - options: - - id: 55 - product_id: 4 - display_name: Add-a-$5-Donation1535042499-187 - type: radio_buttons - config: - default_value: string - checked_by_default: true - checkbox_label: string - date_limited: true - date_limit_mode: range - date_earliest_value: '2019-08-24T00:00:00+00:00' - date_latest_value: '2019-08-24T00:00:00+00:00' - file_types_mode: specific - file_types_supported: - - 'images, documents, other' - file_types_other: - - pdf - file_max_size: 5 - text_characters_limited: true - text_min_length: 1 - text_max_length: 55 - text_lines_limited: true - text_max_lines: 4 - number_limited: true - number_limit_mode: lowest - number_lowest_value: 100 - number_highest_value: 0 - number_integers_only: false - product_list_adjusts_inventory: true - product_list_adjusts_pricing: true - product_list_shipping_calc: weight - sort_order: 1 - option_values: - is_default: false - label: Green - sort_order: 0 - value_data: {} - id: 0 - modifiers: - - type: date - required: true - sort_order: 0 - config: - default_value: string - checked_by_default: true - checkbox_label: string - date_limited: true - date_limit_mode: range - date_earliest_value: '2019-08-24T00:00:00+00:00' - date_latest_value: '2019-08-24T00:00:00+00:00' - file_types_mode: specific - file_types_supported: - - 'images, documents, other' - file_types_other: - - pdf - file_max_size: 5 - text_characters_limited: true - text_min_length: 1 - text_max_length: 55 - text_lines_limited: true - text_max_lines: 4 - number_limited: true - number_limit_mode: lowest - number_lowest_value: 100 - number_highest_value: 0 - number_integers_only: false - product_list_adjusts_inventory: true - product_list_adjusts_pricing: true - product_list_shipping_calc: weight - display_name: string - id: 12 - product_id: 77 - name: Add-a-$5-Donation1535039590-191 - option_values: - - is_default: false - label: Green - sort_order: 0 - value_data: {} - adjusters: - price: - adjuster: relative - adjuster_value: 5 - weight: - adjuster: relative - adjuster_value: 5 - image_url: 'https://cdn8.bigcommerce.com/s-{{store_hash}}/products/184/images/445/naturalcanvascart2_1024x1024__92347__29648.1534344533.1280.1280.jpg?c=2' - purchasing_disabled: - status: true - message: string - id: 0 - option_id: 0 - option_set_id: 0 - option_set_display: string - variants: - - cost_price: 0 - price: 0 - sale_price: 0 - retail_price: 0 - weight: 0 - width: 0 - height: 0 - depth: 0 - is_free_shipping: true - fixed_cost_shipping_price: 0 - purchasing_disabled: true - purchasing_disabled_message: string - upc: string - inventory_level: 0 - inventory_warning_level: 0 - bin_picking_number: string - mpn: string - gtin: 12345678905 - id: 0 - product_id: 0 - sku: string - sku_id: 0 - option_values: - - option_display_name: Color - label: Beige - id: 146 - option_id: 151 - calculated_price: 0 - calculated_weight: 0 - meta: {} - '201': - description: Created - content: - application/json: - schema: - type: object - properties: {} - '207': - description: |- - Multi-status. The product information was updated successfully, but the inventory data failed to update. - - Verify that the inventory-related updates are well-formed and correct; for example, that they donʼt result in negative stock levels. Then consider updating the inventory data again. - content: - application/json: - schema: - type: object - properties: - data: - $ref: '#/components/schemas/product_Full' - errors: - $ref: '#/components/schemas/errorMultiStatus' - meta: - $ref: '#/components/schemas/metaCollection_Full' - '404': - description: | - The resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - '409': - description: | - `Product` was in conflict with another product. This is caused by: duplicate unique values, such as name or SKU; a missing category, brand, or tax_class with which the product is being associated; or a conflicting bulk pricing rule. - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - '422': - description: | - `Product` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - x-codegen-request-body-name: product - delete: - tags: - - Products - summary: Delete a Product - description: Deletes a *Product*. - operationId: deleteProductById - responses: - '204': - description: '' - content: {} - parameters: - - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/ProductIdParam' - '/catalog/products/{product_id}/images': - get: - tags: - - Product Images - summary: Get All Product Images - description: Returns a list of *Product Images*. Optional parameters can be passed in. - operationId: getProductImages - parameters: - - name: page - in: query - description: Specifies the page number in a limited (paginated) list of products. - schema: - type: integer - - name: limit - in: query - description: Controls the number of items per page in a limited (paginated) list of products. - schema: - type: integer - - name: include_fields - in: query - description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' - schema: - type: string - - name: exclude_fields - in: query - description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' - schema: - type: string - responses: - '200': - description: '' - content: - application/json: - schema: - title: Product Image Collection Response - type: object - properties: - data: - type: array - items: - title: Product Image - type: object - allOf: - - $ref: '#/components/schemas/productImage_Full' - meta: - $ref: '#/components/schemas/metaCollection_Full' - description: | - Response payload for the BigCommerce API. - example: - data: - - id: 382 - product_id: 158 - is_thumbnail: true - sort_order: 0 - description: '' - image_file: a/521/foglinenbeigestripetowel1b_1024x1024__83011__60806.jpg - url_zoom: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/382/foglinenbeigestripetowel1b_1024x1024__83011__60806.1534344511.1280.1280.jpg?c=2' - url_standard: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/382/foglinenbeigestripetowel1b_1024x1024__83011__60806.1534344511.560.850.jpg?c=2' - url_thumbnail: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/382/foglinenbeigestripetowel1b_1024x1024__83011__60806.1534344511.330.500.jpg?c=2' - url_tiny: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/382/foglinenbeigestripetowel1b_1024x1024__83011__60806.1534344511.66.100.jpg?c=2' - date_modified: '2018-08-15T14:48:31+00:00' - - id: 383 - product_id: 158 - is_thumbnail: false - sort_order: 0 - description: '' - image_file: k/050/foglinenbeigestripetowel2b_1024x1024__16082__46564.jpg - url_zoom: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/383/foglinenbeigestripetowel2b_1024x1024__16082__46564.1534344511.1280.1280.jpg?c=2' - url_standard: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/383/foglinenbeigestripetowel2b_1024x1024__16082__46564.1534344511.560.850.jpg?c=2' - url_thumbnail: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/383/foglinenbeigestripetowel2b_1024x1024__16082__46564.1534344511.330.500.jpg?c=2' - url_tiny: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/383/foglinenbeigestripetowel2b_1024x1024__16082__46564.1534344511.66.100.jpg?c=2' - date_modified: '2018-08-15T14:48:31+00:00' - meta: - pagination: - total: 2 - count: 2 - per_page: 50 - current_page: 1 - total_pages: 1 - links: - current: '?page=1&limit=50' - '204': - description: | - There are not any images on this product. - content: {} - '404': - description: | - The product ID does not exist. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - post: - tags: - - Product Images - summary: Create a Product Image - description: |- - Creates a *Product Image*. - - **Required Fields** - - `image_file`, or - - `image_url` - - **Usage Notes** - - `image_url` - `255` character limit - - For file uploads, use the `multipart/form-data` media type - - Only one image at a time can be created - - Supported image file types are BMP, GIF, JPEG, PNG, WBMP, XBM, and WEBP. - operationId: createProductImage - parameters: - - $ref: '#/components/parameters/ContentType' - requestBody: - content: - application/json: - schema: - title: Product Image Post - description: The model for a POST to create an image on a product. - allOf: - - title: Product Image Base - type: object - properties: - product_id: - type: integer - description: | - The unique numeric identifier for the product with which the image is associated. - image_file: - type: string - description: |- - The local path to the original image file uploaded to BigCommerce. - A `multipart/form-data` media type. - url_zoom: - type: string - description: | - The zoom URL for this image. By default, this is used as the zoom image on product pages when zoom images are enabled. - url_standard: - type: string - description: | - The standard URL for this image. By default, this is used for product-page images. - url_thumbnail: - type: string - description: | - The thumbnail URL for this image. By default, this is the image size used on the category page and in side panels. - url_tiny: - type: string - description: | - The tiny URL for this image. By default, this is the image size used for thumbnails beneath the product image on a product page. - date_modified: - type: string - description: | - The date on which the product image was modified. - format: date-time - is_thumbnail: - type: boolean - description: | - Flag for identifying whether the image is used as the product's thumbnail. - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the image will be displayed on the product page. Higher integers give the image a lower priority. When updating, if the image is given a lower priority, all images with a `sort_order` the same as or greater than the image's new `sort_order` value will have their `sort_order`s reordered. - description: - type: string - description: | - The description for the image. - description: Common ProductImage properties. - - type: object - properties: - image_url: - type: string - description: | - Must be a fully qualified URL path, including protocol. Limit of 8MB per file. - image_file: - type: string - description: | - Must be sent as a multipart/form-data field in the request body. Limit of 1MB per file. - multipart/form-data: - schema: - title: Product Image Post - description: The model for a POST to create an image on a product. - allOf: - - title: Product Image Base - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the image; increments sequentially. - product_id: - type: integer - description: | - The unique numeric identifier for the product with which the image is associated. - image_file: - type: string - description: |- - The local path to the original image file uploaded to BigCommerce. - A `multipart/form-data` media type. - url_zoom: - type: string - description: | - The zoom URL for this image. By default, this is used as the zoom image on product pages when zoom images are enabled. - url_standard: - type: string - description: | - The standard URL for this image. By default, this is used for product-page images. - url_thumbnail: - type: string - description: | - The thumbnail URL for this image. By default, this is the image size used on the category page and in side panels. - url_tiny: - type: string - description: | - The tiny URL for this image. By default, this is the image size used for thumbnails beneath the product image on a product page. - date_modified: - type: string - description: | - The date on which the product image was modified. - format: date-time - is_thumbnail: - type: boolean - description: | - Flag for identifying whether the image is used as the product's thumbnail. - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the image will be displayed on the product page. Higher integers give the image a lower priority. When updating, if the image is given a lower priority, all images with a `sort_order` the same as or greater than the image's new `sort_order` value will have their `sort_order`s reordered. - description: - type: string - description: | - The description for the image. - description: Common ProductImage properties. - - type: object - properties: - image_url: - type: string - description: | - Must be a fully qualified URL path, including protocol. Limit of 8MB per file. - image_file: - type: string - description: | - Must be sent as a multipart/form-data field in the request body. Limit of 1MB per file. - required: true - responses: - '200': - description: Success - content: - application/json: - schema: - title: Product Image Response - type: object - properties: - data: - title: Product Image - type: object - allOf: - - title: Product Image Base - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the image; increments sequentially. - product_id: - type: integer - description: | - The unique numeric identifier for the product with which the image is associated. - image_file: - type: string - description: |- - The local path to the original image file uploaded to BigCommerce. - - A `multipart/form-data` media type. - url_zoom: - type: string - description: | - The zoom URL for this image. By default, this is used as the zoom image on product pages when zoom images are enabled. - url_standard: - type: string - description: | - The standard URL for this image. By default, this is used for product-page images. - url_thumbnail: - type: string - description: | - The thumbnail URL for this image. By default, this is the image size used on the category page and in side panels. - url_tiny: - type: string - description: | - The tiny URL for this image. By default, this is the image size used for thumbnails beneath the product image on a product page. - date_modified: - type: string - description: | - The date on which the product image was modified. - format: date-time - is_thumbnail: - type: boolean - description: | - Flag for identifying whether the image is used as the product's thumbnail. - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the image will be displayed on the product page. Higher integers give the image a lower priority. When updating, if the image is given a lower priority, all images with a `sort_order` the same as or greater than the image's new `sort_order` value will have their `sort_order`s reordered. - description: - type: string - description: | - The description for the image. - description: Common ProductImage properties. - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the image; increments sequentially. - product_id: - type: integer - description: | - The unique numeric identifier for the product with which the image is associated. - image_file: - type: string - description: |- - The local path to the original image file uploaded to BigCommerce. Use image_url when creating a product. - A `multipart/form-data` media type. - url_zoom: - type: string - description: | - The zoom URL for this image. By default, this is used as the zoom image on product pages when zoom images are enabled. - url_standard: - type: string - description: | - The standard URL for this image. By default, this is used for product-page images. - url_thumbnail: - type: string - description: | - The thumbnail URL for this image. By default, this is the image size used on the category page and in side panels. - url_tiny: - type: string - description: | - The tiny URL for this image. By default, this is the image size used for thumbnails beneath the product image on a product page. - date_modified: - type: string - description: | - The date on which the product image was modified. - format: date-time - image_url: - type: string - description: |- - Publically available URL. - Use the image_url when creating a product. - example: 'https://upload.wikimedia.org/wikipedia/commons/7/7f/Anglel_Bless_Legendary_Hills_1_m%C4%9Bs%C3%ADc_st%C3%A1%C5%99%C3%AD.jpg' - meta: - $ref: '#/components/schemas/metaEmpty_Full' - description: | - Response payload for the BigCommerce API. - example: - data: - id: 485 - product_id: 158 - is_thumbnail: false - sort_order: 1 - description: '' - image_file: o/381/product-image__98178.png - url_zoom: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/485/product-image__98178.1536854227.1280.1280.png?c=2' - url_standard: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/485/product-image__98178.1536854227.560.850.png?c=2' - url_thumbnail: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/485/product-image__98178.1536854227.330.500.png?c=2' - url_tiny: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/485/product-image__98178.1536854227.66.100.png?c=2' - date_modified: '2018-09-13T15:57:07+00:00' - meta: {} - '400': - description: Bad Request. The requested resource could not be downloaded and may be invalid. Possible reasons include malformed request syntax or the file host blocking requests. - content: - application/json: - schema: - type: object - properties: {} - '404': - description: | - The product ID does not exist. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - '422': - description: |- - Unprocessable Entity. - - May occur if the `Content-Type` header is set to `multipart/form-data` rather than `application/json` when creating a product image using `image_url`. - content: - application/json: - schema: - required: - - status - - title - - type - type: object - properties: - status: - type: number - title: - minLength: 1 - type: string - type: - minLength: 1 - type: string - description: '' - example: - status: 422 - title: image_url must be present if uploading by url - type: /api-docs/getting-started/api-status-codes - x-codegen-request-body-name: productImage - parameters: - - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/ProductIdParam' - '/catalog/products/{product_id}/images/{image_id}': - get: - tags: - - Product Images - summary: Get a Product Image - description: Returns a single *Product Image*. Optional parameters can be passed in. - operationId: getProductImageById - parameters: - - name: image_id - in: path - description: | - The ID of the `Image` that is being operated on. - required: true - schema: - type: integer - - - name: include_fields - in: query - description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' - schema: - type: string - - name: exclude_fields - in: query - description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' - schema: - type: string - responses: - '200': - description: '' - content: - application/json: - schema: - title: Product Image Response - type: object - properties: - data: - $ref: '#/components/schemas/productImage_Full' - meta: - $ref: '#/components/schemas/metaEmpty_Full' - description: | - Response payload for the BigCommerce API. - example: - data: - id: 485 - product_id: 158 - is_thumbnail: false - sort_order: 1 - description: '' - image_file: o/381/product-image__98178.png - url_zoom: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/485/product-image__98178.1536854227.1280.1280.png?c=2' - url_standard: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/485/product-image__98178.1536854227.560.850.png?c=2' - url_thumbnail: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/485/product-image__98178.1536854227.330.500.png?c=2' - url_tiny: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/485/product-image__98178.1536854227.66.100.png?c=2' - date_modified: '2018-09-13T15:57:07+00:00' - meta: {} - '404': - description: | - The resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - put: - tags: - - Product Images - summary: Update a Product Image - description: |- - Updates a *Product Image*. - - **Usage Notes** - - `image_url` - `255` character limit - - For file uploads, send a POST request using the `multipart/form-data` media type - operationId: updateProductImage - parameters: - - $ref: '#/components/parameters/ContentType' - - name: image_id - in: path - description: | - The ID of the `Image` that is being operated on. - required: true - schema: - type: integer - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/productImage_Put' - required: true - responses: - '200': - description: '' - content: - application/json: - schema: - title: Product Image Response - type: object - properties: - data: - title: Product Image - type: object - allOf: - - title: Product Image Base - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the image; increments sequentially. - product_id: - type: integer - description: | - The unique numeric identifier for the product with which the image is associated. - image_file: - type: string - description: | - The local path to the original image file uploaded to BigCommerce. - url_zoom: - type: string - description: | - The zoom URL for this image. By default, this is used as the zoom image on product pages when zoom images are enabled. - url_standard: - type: string - description: | - The standard URL for this image. By default, this is used for product-page images. - url_thumbnail: - type: string - description: | - The thumbnail URL for this image. By default, this is the image size used on the category page and in side panels. - url_tiny: - type: string - description: | - The tiny URL for this image. By default, this is the image size used for thumbnails beneath the product image on a product page. - date_modified: - type: string - description: | - The date on which the product image was modified. - format: date-time - is_thumbnail: - type: boolean - description: | - Flag for identifying whether the image is used as the product's thumbnail. - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the image will be displayed on the product page. Higher integers give the image a lower priority. When updating, if the image is given a lower priority, all images with a `sort_order` the same as or greater than the image's new `sort_order` value will have their `sort_order`s reordered. - description: - type: string - description: | - The description for the image. - description: Common ProductImage properties. - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the image; increments sequentially. - product_id: - type: integer - description: | - The unique numeric identifier for the product with which the image is associated. - image_file: - type: string - description: | - The local path to the original image file uploaded to BigCommerce. Use image_url when creating a product. - url_zoom: - type: string - description: | - The zoom URL for this image. By default, this is used as the zoom image on product pages when zoom images are enabled. - url_standard: - type: string - description: | - The standard URL for this image. By default, this is used for product-page images. - url_thumbnail: - type: string - description: | - The thumbnail URL for this image. By default, this is the image size used on the category page and in side panels. - url_tiny: - type: string - description: | - The tiny URL for this image. By default, this is the image size used for thumbnails beneath the product image on a product page. - date_modified: - type: string - description: | - The date on which the product image was modified. - format: date-time - image_url: - type: string - description: |- - Publically available URL. - Use the image_url when creating a product. - example: 'https://upload.wikimedia.org/wikipedia/commons/7/7f/Anglel_Bless_Legendary_Hills_1_m%C4%9Bs%C3%ADc_st%C3%A1%C5%99%C3%AD.jpg' - meta: - $ref: '#/components/schemas/metaEmpty_Full' - description: | - Response payload for the BigCommerce API. - example: - data: - id: 485 - product_id: 158 - is_thumbnail: false - sort_order: 1 - description: '' - image_file: o/381/product-image__98178.png - url_zoom: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/485/product-image__98178.1536854227.1280.1280.png?c=2' - url_standard: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/485/product-image__98178.1536854227.560.850.png?c=2' - url_thumbnail: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/485/product-image__98178.1536854227.330.500.png?c=2' - url_tiny: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/485/product-image__98178.1536854227.66.100.png?c=2' - date_modified: '2018-09-13T15:57:07+00:00' - meta: {} - '201': - description: Created - content: - application/json: - schema: - type: object - properties: {} - '400': - description: Bad Request. The requested resource could not be downloaded and may be invalid. Possible reasons include malformed request syntax or the file host blocking requests. - content: - application/json: - schema: - type: object - properties: {} - '404': - description: | - The resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - x-codegen-request-body-name: productImage - delete: - tags: - - Product Images - summary: Delete a Product Image - description: Deletes a *Product Image*. - operationId: deleteProductImage - parameters: - - name: image_id - in: path - description: | - The ID of the `Image` that is being operated on. - required: true - schema: - type: integer - responses: - '204': - description: '' - content: {} - parameters: - - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/ProductIdParam' - - $ref: '#/components/parameters/ImageIdParam' - '/catalog/products/{product_id}/videos': - get: - tags: - - Product Videos - summary: Get All Product Videos - description: Returns a list of *Product Videos*. Optional parameters can be passed in. - operationId: getProductVideos - parameters: - - name: include_fields - in: query - description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' - schema: - type: string - - name: exclude_fields - in: query - description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' - schema: - type: string - - name: page - in: query - description: Specifies the page number in a limited (paginated) list of products. - schema: - type: integer - - name: limit - in: query - description: Controls the number of items per page in a limited (paginated) list of products. - schema: - type: integer - responses: - '200': - description: '' - content: - application/json: - schema: - title: Product Video Collection Response - type: object - properties: - data: - type: array - items: - $ref: '#/components/schemas/productVideo_Full' - meta: - $ref: '#/components/schemas/metaCollection_Full' - example: - data: - - id: 6 - type: youtube - video_id: PqBTp23RLhI - product_id: 192 - sort_order: 1 - title: Creating and Editing Banners | BigCommerce Tutorials - description: 'Learn how to create and edit marketing banners. Marketing banners are a great way to advertise sales, display coupon codes, and add design elements. Let’s take a look at how you can leverage banners to convert your store’s visitors into paying customers.' - length: '01:54' - - id: 7 - type: youtube - video_id: EhYBjzqd-nI - product_id: 192 - sort_order: 2 - title: BigCommerce Company Values - description: |- - These are the core principles upon which BigCommerce was built, guiding what we do and how we do it. Each employee learns them, loves them and lives them. Our merchants benefit from them every time they use our product or get help from our support team. - - Join the BigCommerce team and help us build software that changes lives! - - https://www.bigcommerce.com/careers/ - length: '03:30' - - id: 8 - type: youtube - video_id: vAUdo4kRjrU - product_id: 192 - sort_order: 3 - title: TOP WORKPLACES 2016 - Austin American Statesman + BigCommerce - description: |- - We've been named one of Austin American-Statesman's Top WorkPlaces for the 5th year in a row! Here's what some employees have to say: - - “I am given the freedom and trust to make a difference.” - - “Everyone believes in the product and growing the company.” - - “I'm appreciated for the work I do and there is room to grown within the company.” - - Work With Us! - http://www.bigcommerce.com/careers.php - length: '01:37' - meta: - pagination: - total: 3 - count: 3 - per_page: 50 - current_page: 1 - total_pages: 1 - links: - current: '?page=1&limit=50' - post: - tags: - - Product Videos - summary: Create a Product Video - description: |- - Creates a *Product Video*. - - **Required Fields** - * video_id - - **Read-Only Fields** - * id - - Publicly accessible URLs are valid parameters. - Videos must be loaded through YouTube at this time. - operationId: createProductVideo - parameters: - - $ref: '#/components/parameters/ContentType' - requestBody: - content: - application/json: - schema: - title: Product Video Post - description: | - The model for a POST to create a video on a product. - allOf: - - title: Product Video Base - description: Common Product Video properties. - properties: - title: - maxLength: 255 - minLength: 0 - type: string - example: Writing Great Documentation - description: | - The title for the video. If left blank, this will be filled in according to data on a host site. - description: - type: string - example: A video about documenation - description: | - The description for the video. If left blank, this will be filled in according to data on a host site. - sort_order: - maximum: 2147483647 - minimum: -2147483648 - example: 1 - type: integer - description: | - The order in which the video will be displayed on the product page. Higher integers give the video a lower priority. When updating, if the video is given a lower priority, all videos with a `sort_order` the same as or greater than the video's new `sort_order` value will have their `sort_order`s reordered. - type: - type: string - description: | - The video type (a short name of a host site). - enum: - - youtube - - properties: - video_id: - type: string - maxLength: 25 - minLength: 0 - description: | - The ID of the video on a host site. - x-required: - - post - example: z3fRu9pkuXE - type: object - required: true - responses: - '200': - description: '' - content: - application/json: - schema: - title: Product Video Response - type: object - properties: - data: - title: Product Video - type: object - description: | - A product video model. - allOf: - - title: Product Video Base - type: object - properties: - title: - maxLength: 255 - minLength: 0 - type: string - description: | - The title for the video. If left blank, this will be filled in according to data on a host site. - description: - type: string - description: | - The description for the video. If left blank, this will be filled in according to data on a host site. - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the video will be displayed on the product page. Higher integers give the video a lower priority. When updating, if the video is given a lower priority, all videos with a `sort_order` the same as or greater than the video's new `sort_order` value will have their `sort_order`s reordered. - type: - type: string - description: | - The video type (a short name of a host site). - enum: - - youtube - description: Common Product Video properties. - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the product video; increments sequentially. - video_id: - type: string - description: | - The ID of the video on a host site. - product_id: - type: integer - description: | - The unique numeric identifier for the product with which the image is associated. - length: - type: string - description: | - Length of the video. This will be filled in according to data on a host site. - meta: - $ref: '#/components/schemas/metaEmpty_Full' - description: | - Response payload for the BigCommerce API. - example: - title: Your Video - description: Company Values - sort_order: 1 - type: youtube - video_id: 123345AA - '404': - description: | - The resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - x-codegen-request-body-name: productVideo - parameters: - - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/ProductIdParam' - '/catalog/products/{product_id}/videos/{id}': - get: - tags: - - Product Videos - summary: Get a Product Video - description: Returns a single *Product Video*. Optional parameters can be passed in. - operationId: getProductVideoById - parameters: - - name: id - in: path - description: The BigCommerce ID of the `Video` - required: true - schema: - type: integer - - - name: include_fields - in: query - description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' - schema: - type: string - - name: exclude_fields - in: query - description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' - schema: - type: string - responses: - '200': - description: '' - content: - application/json: - schema: - title: Product Video Response - type: object - properties: - data: - $ref: '#/components/schemas/productVideo_Full' - meta: - $ref: '#/components/schemas/metaEmpty_Full' - description: | - Response payload for the BigCommerce API. - example: - title: Your Video - description: Company Values - sort_order: 1 - type: youtube - video_id: 123345AA - '404': - description: | - The resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - put: - tags: - - Product Videos - summary: Update a Product Video - description: |- - Updates a *Product Video. - - **Required Fields** - * none - - **Read-Only Fields** - * id - operationId: updateProductVideo - parameters: - - $ref: '#/components/parameters/ContentType' - - name: id - in: path - description: The BigCommerce ID of the `Video` - required: true - schema: - type: integer - requestBody: - content: - application/json: - schema: - title: Product Video Put - description: | - The model for a PUT to update a video on a product. - allOf: - - title: Product Video Base - type: object - properties: - title: - maxLength: 255 - minLength: 0 - type: string - description: | - The title for the video. If left blank, this will be filled in according to data on a host site. - description: - type: string - description: | - The description for the video. If left blank, this will be filled in according to data on a host site. - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the video will be displayed on the product page. Higher integers give the video a lower priority. When updating, if the video is given a lower priority, all videos with a `sort_order` the same as or greater than the video's new `sort_order` value will have their `sort_order`s reordered. - type: - type: string - description: | - The video type (a short name of a host site). - enum: - - youtube - description: Common Product Video properties. - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the product video; increments sequentially. - x-required: - - put - required: true - responses: - '200': - description: '' - content: - application/json: - schema: - title: Product Video Response - type: object - properties: - data: - title: Product Video - type: object - description: | - A product video model. - allOf: - - title: Product Video Base - type: object - properties: - title: - maxLength: 255 - minLength: 0 - type: string - description: | - The title for the video. If left blank, this will be filled in according to data on a host site. - description: - type: string - description: | - The description for the video. If left blank, this will be filled in according to data on a host site. - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the video will be displayed on the product page. Higher integers give the video a lower priority. When updating, if the video is given a lower priority, all videos with a `sort_order` the same as or greater than the video's new `sort_order` value will have their `sort_order`s reordered. - type: - type: string - description: | - The video type (a short name of a host site). - enum: - - youtube - description: Common Product Video properties. - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the product video; increments sequentially. - video_id: - type: string - description: | - The ID of the video on a host site. - product_id: - type: integer - description: | - The unique numeric identifier for the product with which the image is associated. - length: - type: string - description: | - Length of the video. This will be filled in according to data on a host site. - meta: - $ref: '#/components/schemas/metaEmpty_Full' - description: | - Response payload for the BigCommerce API. - example: - title: Your Video - description: Company Values - sort_order: 1 - type: youtube - video_id: 123345AA - '404': - description: | - The resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - x-codegen-request-body-name: productVideo - delete: - tags: - - Product Videos - summary: Delete a Product Video - description: Deletes a *Product Video*. - operationId: deleteProductVideo - parameters: - - name: id - in: path - description: The BigCommerce ID of the `Video` - required: true - schema: - type: integer - responses: - '204': - description: '' - content: {} - parameters: - - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/ProductIdParam' - - $ref: '#/components/parameters/VideoIdParam' - '/catalog/products/{product_id}/variants': - get: - tags: - - Product Variants - summary: Get All Product Variants - description: Returns a list of product *Variants*. Optional parameters can be passed in. - operationId: getVariantsByProductId - parameters: - - name: page - in: query - description: Specifies the page number in a limited (paginated) list of products. - schema: - type: integer - - name: limit - in: query - description: Controls the number of items per page in a limited (paginated) list of products. - schema: - type: integer - - name: include_fields - in: query - description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' - schema: - type: string - - name: exclude_fields - in: query - description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' - schema: - type: string - responses: - '200': - description: '' - content: - application/json: - schema: - title: Variant Collection Response - type: object - properties: - data: - type: array - items: - $ref: '#/components/schemas/productVariant_Full' - meta: - $ref: '#/components/schemas/metaCollection_Full' - example: - data: - - id: 382 - product_id: 192 - sku: SMIT - sku_id: 348 - price: 10 - calculated_price: 10 - sale_price: 8 - retail_price: 10 - map_price: {} - weight: 4 - calculated_weight: 2 - width: 5 - height: 5 - depth: 5 - is_free_shipping: false - fixed_cost_shipping_price: 10 - purchasing_disabled: false - purchasing_disabled_message: '' - image_url: '' - cost_price: 0 - upc: '' - mpn: '' - gtin: '' - inventory_level: 0 - inventory_warning_level: 0 - bin_picking_number: '' - option_values: - - id: 174 - label: Beige - option_id: 220 - option_display_name: Color - - id: 383 - product_id: 192 - sku: SMIT-1 - sku_id: 349 - price: 25 - calculated_price: 25 - sale_price: 20 - retail_price: 25 - map_price: {} - weight: 2 - calculated_weight: 1 - width: 5 - height: 5 - depth: 5 - is_free_shipping: false - fixed_cost_shipping_price: 10 - purchasing_disabled: false - purchasing_disabled_message: '' - image_url: '' - cost_price: 25 - upc: '' - mpn: '' - gtin: '' - inventory_level: 0 - inventory_warning_level: 0 - bin_picking_number: '' - option_values: - - id: 175 - label: Grey - option_id: 220 - option_display_name: Color - - id: 384 - product_id: 192 - sku: SMIT-2 - sku_id: 350 - price: 25 - calculated_price: 25 - sale_price: 20 - retail_price: 25 - map_price: {} - weight: 2 - calculated_weight: 1 - width: 5 - height: 5 - depth: 5 - is_free_shipping: false - fixed_cost_shipping_price: 10 - purchasing_disabled: false - purchasing_disabled_message: '' - image_url: '' - cost_price: 25 - upc: '' - mpn: '' - gtin: '' - inventory_level: 0 - inventory_warning_level: 0 - bin_picking_number: '' - option_values: - - id: 176 - label: Black - option_id: 220 - option_display_name: Color - meta: - pagination: - total: 3 - count: 3 - per_page: 50 - current_page: 1 - total_pages: 1 - links: - current: '?page=1&limit=50' - '404': - description: | - The resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - post: - tags: - - Product Variants - summary: Create a Product Variant - description: |- - Creates a *Product Variant*. - - **Required Fields** - * sku - * option_values - - **Read-Only Fields** - * id - - **Limits** - * 600 SKUs per product limit. - * 255 characters SKU length limit. - - Variants need to be created one at a time using this endpoint. To use a variant array and create products and variants in the same call use the [Create Products](/docs/rest-management/catalog/products#create-a-product) during the initial product creation. - operationId: createVariant - parameters: - - $ref: '#/components/parameters/ContentType' - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/productVariant_Post' - required: true - responses: - '200': - description: '' - content: - application/json: - schema: - title: Variant Response - type: object - properties: - data: - $ref: '#/components/schemas/productVariant_Full' - meta: - $ref: '#/components/schemas/metaEmpty_Full' - examples: - example-1: - value: - data: - cost_price: 0 - price: 0 - sale_price: 0 - retail_price: 0 - weight: 0 - width: 0 - height: 0 - depth: 0 - is_free_shipping: true - fixed_cost_shipping_price: 0 - purchasing_disabled: true - purchasing_disabled_message: string - upc: string - inventory_level: 0 - inventory_warning_level: 0 - bin_picking_number: string - mpn: string - gtin: '012345678905' - id: 0 - product_id: 0 - sku: string - sku_id: 0 - option_values: - - option_display_name: Color - label: Beige - id: 146 - option_id: 151 - calculated_price: 0 - calculated_weight: 0 - meta: {} - example-2: - value: - data: - id: 384 - product_id: 192 - sku: SMIT-2 - sku_id: 350 - price: 25 - calculated_price: 25 - sale_price: 20 - retail_price: 25 - map_price: {} - weight: 2 - calculated_weight: 1 - width: 5 - height: 5 - depth: 5 - is_free_shipping: false - fixed_cost_shipping_price: 10 - purchasing_disabled: false - purchasing_disabled_message: '' - image_url: '' - cost_price: 25 - upc: '' - mpn: '' - gtin: '' - inventory_level: 0 - inventory_warning_level: 0 - bin_picking_number: '' - option_values: - - id: 176 - label: Black - option_id: 220 - option_display_name: Color - meta: {} - '207': - description: |- - Multi-status. The product information was updated successfully, but the inventory data failed to update. - - Verify that the inventory-related updates are well-formed and correct; for example, that they donʼt result in negative stock levels. Then consider updating the inventory data again. - content: - application/json: - schema: - type: object - properties: - data: - $ref: '#/components/schemas/productVariant_Full' - errors: - $ref: '#/components/schemas/errorMultiStatus' - meta: - $ref: '#/components/schemas/metaCollection_Full' - '404': - description: | - The resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - x-codegen-request-body-name: Variant - parameters: - - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/ProductIdParam' - '/catalog/products/{product_id}/variants/{variant_id}': - get: - tags: - - Product Variants - summary: Get a Product Variant - description: Returns a single product *Variant*. Optional parameters can be passed in. - operationId: getVariantById - parameters: - - name: variant_id - in: path - description: | - ID of the variant on a product, or on an associated Price List Record. - required: true - schema: - type: integer - - - name: include_fields - in: query - description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' - schema: - type: string - - name: exclude_fields - in: query - description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' - schema: - type: string - responses: - '200': - description: '' - content: - application/json: - schema: - title: Variant Response - type: object - properties: - data: - $ref: '#/components/schemas/productVariant_Full' - meta: - $ref: '#/components/schemas/metaEmpty_Full' - example: - data: - id: 384 - product_id: 192 - sku: SMIT-2 - sku_id: 350 - price: 25 - calculated_price: 25 - sale_price: 20 - retail_price: 25 - map_price: {} - weight: 2 - calculated_weight: 1 - width: 5 - height: 5 - depth: 5 - is_free_shipping: false - fixed_cost_shipping_price: 10 - purchasing_disabled: false - purchasing_disabled_message: '' - image_url: '' - cost_price: 25 - upc: '' - mpn: '' - gtin: '' - inventory_level: 0 - inventory_warning_level: 0 - bin_picking_number: '' - option_values: - - id: 176 - label: Black - option_id: 220 - option_display_name: Color - meta: {} - '404': - description: | - The resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - put: - tags: - - Product Variants - summary: Update a Product Variant - description: Updates a product *Variant*. - operationId: updateVariant - parameters: - - $ref: '#/components/parameters/ContentType' - - name: variant_id - in: path - description: | - ID of the variant on a product, or on an associated Price List Record. - required: true - schema: - type: integer - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/productVariant_Put' - required: true - responses: - '200': - description: '' - content: - application/json: - schema: - title: Variant Response - type: object - properties: - data: - $ref: '#/components/schemas/productVariant_Full' - meta: - $ref: '#/components/schemas/metaEmpty_Full' - example: - data: - bin_picking_number: '0' - calculated_price: 85 - calculated_weight: 1 - cost_price: 0 - depth: 22 - fixed_cost_shipping_price: 0 - gtin: '' - height: 14.6 - id: 65 - inventory_level: 0 - inventory_warning_level: 0 - is_free_shipping: false - map_price: 0 - mpn: TR-SML02 - option_values: [] - price: 89 - product_id: 81 - purchasing_disabled: true - purchasing_disabled_message: This item is not available. - retail_price: 89 - sale_price: 85 - sku: OTS - sku_id: 10 - upc: '' - weight: 1 - width: 2 - meta: {} - '207': - description: |- - Multi-status. The product information was updated successfully, but the inventory data failed to update. - - Verify that the inventory-related updates are well-formed and correct; for example, that they donʼt result in negative stock levels. Then consider updating the inventory data again. - content: - application/json: - schema: - type: object - properties: - data: - $ref: '#/components/schemas/productVariant_Full' - errors: - $ref: '#/components/schemas/errorMultiStatus' - meta: - $ref: '#/components/schemas/metaCollection_Full' - '404': - description: | - The resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - x-codegen-request-body-name: Variant - delete: - tags: - - Product Variants - summary: Delete a Product Variant - description: Deletes a product *Variant*. - operationId: deleteVariantById - parameters: - - name: variant_id - in: path - description: | - ID of the variant on a product, or on an associated Price List Record. - required: true - schema: - type: integer - responses: - '204': - description: '' - content: {} - parameters: - - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/ProductIdParam' - - $ref: '#/components/parameters/VariantIdParam' - '/catalog/products/{product_id}/variants/{variant_id}/metafields': - get: - tags: - - Product Variants Metafields - summary: Get All Product Variant Metafields - description: Returns a list of product variant *Metafields*. Optional parameters can be passed in. - operationId: getVariantMetafieldsByProductIdAndVariantId - parameters: - - name: variant_id - in: path - description: | - ID of the variant on a product, or on an associated Price List Record. - required: true - schema: - type: integer - - - name: page - in: query - description: Specifies the page number in a limited (paginated) list of products. - schema: - type: integer - - name: limit - in: query - description: Controls the number of items per page in a limited (paginated) list of products. - schema: - type: integer - - name: key - in: query - description: | - Filter based on a metafield's key. - schema: - type: string - - name: namespace - in: query - description: Filter based on a metafield's namespace. - schema: - type: string - - name: include_fields - in: query - description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' - schema: - type: string - - name: exclude_fields - in: query - description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' - schema: - type: string - responses: - '200': - description: '' - content: - application/json: - schema: - title: Meta Field Collection Response - type: object - properties: - data: - type: array - items: - $ref: '#/components/schemas/metafield_Full' - meta: - $ref: '#/components/schemas/categoriesTree_Resp' - '404': - description: | - The resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - post: - tags: - - Product Variants Metafields - summary: Create a Product Variant Metafield - description: |- - Creates a product variant *Metafield*. - - **Required Fields:** - * permission_set - * namespace - * key - * value - - **Read-Only Fields** - * id - - **Note:** The maxiumum number of metafields allowed on each order, product, category, variant, or brand is 250 per client ID. For more information, see [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center. - operationId: createVariantMetafield - parameters: - - $ref: '#/components/parameters/ContentType' - - name: variant_id - in: path - description: | - ID of the variant on a product, or on an associated Price List Record. - required: true - schema: - type: integer - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/metafield_Base' - required: true - responses: - '200': - description: '' - content: - application/json: - schema: - title: Metafield Response - type: object - properties: - data: - $ref: '#/components/schemas/metafield_Full' - meta: - $ref: '#/components/schemas/metaEmpty_Full' - example: - data: - id: 4 - key: location_id - value: 'Shelf 3, Bin 5' - namespace: App Namespace - permission_set: app_only - resource_type: variant - resource_id: 137 - description: Where products are located - date_created: '2021-08-06T19:15:35+00:00' - date_modified: '2021-08-06T19:15:35+00:00' - meta: {} - '409': - description: | - The `Metafield` was in conflict with another `Metafield`. This can be the result of duplicate unique-key combinations of the app's client id, namespace, key, resource_type, and resource_id. - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - '422': - description: | - The `Metafield` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - x-codegen-request-body-name: Metafield - parameters: - - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/ProductIdParam' - - $ref: '#/components/parameters/VariantIdParam' - '/catalog/products/{product_id}/variants/{variant_id}/metafields/{metafield_id}': - get: - tags: - - Product Variants Metafields - summary: Get a Product Variant Metafields - description: Returns a single product variant *Metafield*. Optional parameters can be passed in. - operationId: getVariantMetafieldByProductIdAndVariantId - parameters: - - name: metafield_id - in: path - description: | - The ID of the `Metafield`. - required: true - schema: - type: integer - - name: variant_id - in: path - description: | - ID of the variant on a product, or on an associated Price List Record. - required: true - schema: - type: integer - - - name: include_fields - in: query - description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' - schema: - type: string - - name: exclude_fields - in: query - description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' - schema: - type: string - responses: - '200': - description: '' - content: - application/json: - schema: - title: Metafield Response - type: object - properties: - data: - $ref: '#/components/schemas/metafield_Full' - meta: - $ref: '#/components/schemas/metaEmpty_Full' - example: - data: - id: 8 - key: location_id - value: 'Shelf 3, Bin 5' - namespace: Inventory Namespace - permission_set: read - resource_type: variant - resource_id: 158 - description: Where products are located - date_created: '2018-09-13T16:42:37+00:00' - date_modified: '2018-09-13T16:42:37+00:00' - meta: {} - '404': - description: | - The resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - put: - tags: - - Product Variants Metafields - summary: Update Product Variant Metafields - description: "Updates a product variant *Metafield*.\n\n**Required Fields:**\n* none\n\n**Read-Only Fields**\n* id\n* These fields can only be modified by the app (API credentials) that created the metafield:\n\t* namespace\n\t* key\n\t* permission_set\n\n**Usage Notes**\n* Attempting to modify `namespace`, `key`, and `permission_set` fields using a client ID different from the one used to create those metafields will result in a 403 error message. " - operationId: updateVariantMetafield - parameters: - - $ref: '#/components/parameters/ContentType' - - name: metafield_id - in: path - description: | - The ID of the `Metafield`. - required: true - schema: - type: integer - - name: variant_id - in: path - description: | - ID of the variant on a product, or on an associated Price List Record. - required: true - schema: - type: integer - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/metafield_Base' - required: true - responses: - '200': - description: '' - content: - application/json: - schema: - title: Metafield Response - type: object - properties: - data: - $ref: '#/components/schemas/metafield_Full' - meta: - $ref: '#/components/schemas/metaEmpty_Full' - example: - data: - id: 8 - key: location_id - value: 'Shelf 3, Bin 5' - namespace: Inventory Namespace - permission_set: read - resource_type: variant - resource_id: 158 - description: Where products are located - date_created: '2018-09-13T16:42:37+00:00' - date_modified: '2018-09-13T16:42:37+00:00' - meta: {} - '404': - description: | - The resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - x-codegen-request-body-name: Metafield - delete: - tags: - - Product Variants Metafields - summary: Delete a Variant Metafield - description: Deletes a product variant *Metafield*. - operationId: deleteVariantMetafieldById - parameters: - - name: metafield_id - in: path - description: | - The ID of the `Metafield`. - required: true - schema: - type: integer - - name: variant_id - in: path - description: | - ID of the variant on a product, or on an associated Price List Record. - required: true - schema: - type: integer - responses: - '204': - description: '' - content: {} - parameters: - - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/ProductIdParam' - - $ref: '#/components/parameters/VariantIdParam' - - $ref: '#/components/parameters/MetafieldIdParam' - '/catalog/products/{product_id}/variants/{variant_id}/image': - post: - tags: - - Product Variants - summary: Create a Variant Image - description: |- - Creates a *Variant Image*. - - The image will show on the storefront when the value is selected. - - **Required Fields** - - image_file: Form posts. Files larger than 1 MB are not accepted - - image_url: Any publicly available URL - operationId: createVariantImage - parameters: - - $ref: '#/components/parameters/ContentType' - - name: variant_id - in: path - description: | - ID of the variant on a product, or on an associated Price List Record. - required: true - schema: - type: integer - requestBody: - content: - application/json: - schema: - type: object - properties: - image_url: - type: string - description: | - A public URL for a GIF, JPEG, or PNG image. Limit of 8MB per file. - description: 'An object containing a publicly accessible image URL, or a form post that contains an image file.' - multipart/form-data: - schema: - type: object - properties: - image_url: - type: string - description: | - A public URL for a GIF, JPEG, or PNG image. Limit of 8MB per file. - description: 'An object containing a publicly accessible image URL, or a form post that contains an image file.' - required: false - responses: - '200': - description: '`image_url` is returned for both `image_file` and `image_url`.' - content: - application/json: - schema: - title: Image Response - type: object - properties: - data: - title: Resource Image - type: object - properties: - image_url: - type: string - description: | - A public URL for a GIF, JPEG, or PNG image. Limit of 8MB per file. - description: 'An object containing a publicly accessible image URL, or a form post that contains an image file.' - meta: - $ref: '#/components/schemas/metaEmpty_Full' - description: |- - Image Response returns for: - * Create Variant Image - * Create Modifier Image - * Create Category Image - * Create Brand Image - example: - data: - image_url: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/product_images/attribute_rule_images/85_source_1536863430.png' - meta: {} - '400': - description: Bad Request. The requested resource could not be downloaded and may be invalid. Possible reasons include malformed request syntax or the file host blocking requests. - content: - application/json: - schema: - type: object - properties: {} - '404': - description: | - The resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - '422': - description: | - Image was not valid. This is the result of a missing `image_file` field or of an incorrect file type. See the response for more details. - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - '500': - description: Returns for an `image_file` larger than 1 MB. - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - x-codegen-request-body-name: body - parameters: - - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/ProductIdParam' - - $ref: '#/components/parameters/VariantIdParam' - '/catalog/products/{product_id}/options': - get: - tags: - - Product Variant Options - summary: Get All Product Variant Options - description: 'Returns a list of product *Variant Options*. Optional parameters can be passed in. ' - operationId: getOptions - parameters: - - name: page - in: query - description: Specifies the page number in a limited (paginated) list of products. - schema: - type: integer - - name: limit - in: query - description: Controls the number of items per page in a limited (paginated) list of products. - schema: - type: integer - - name: include_fields - in: query - description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' - schema: - type: string - - name: exclude_fields - in: query - description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' - schema: - type: string - responses: - '200': - description: '' - content: - application/json: - schema: - title: Option Collection Response - type: object - properties: - data: - type: array - items: - $ref: '#/components/schemas/productOption_Full' - meta: - $ref: '#/components/schemas/metaCollection_Full' - description: Get all product options - '404': - description: | - The resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - post: - tags: - - Product Variant Options - summary: Create a Product Variant Option - description: |- - Creates a *Variant Option*. - - **Required Fields** - * display_name - * type - * option_values - - **Read-Only Fields** - * id - - **Limits** - * 255 characters option name length. - - **Notes** - - * Only one variant option at a time can be created; individual variant options will contain an array of multiple values. - * There are several examples listed below that create options, but the SKU’s are not updated and they are not a variant on the product. Variant SKUs must be created with a separate request. - * Variant options will show on the storefront as an option that can be selected by the customer. A request like this could be used to add new choices to a variant that has already been created. - * If more than one variant needs to be created use the [Create a Product](/docs/rest-management/catalog/products#create-a-product) endpoint. - operationId: createOption - parameters: - - $ref: '#/components/parameters/ContentType' - requestBody: - content: - application/json: - schema: - title: Option Post - description: The model for a POST to create options on a product. - allOf: - - title: Option Base - description: Common Option properties. - properties: - product_id: - type: integer - description: | - The unique numerical ID of the product to which the option belongs. - example: 4 - x-required: - - post - - put - display_name: - maxLength: 255 - minLength: 1 - type: string - description: | - The name of the option shown on the storefront. - example: Add-a-$5-Donation1535042499-187 - x-required: - - post - - put - type: - type: string - description: | - The type of option, which determines how it will display on the storefront. Acceptable values: `radio_buttons`, `rectangles`, `dropdown`, `product_list`, `product_list_with_images`, `swatch`. For reference, the former v2 API values are: RB = radio_buttons, RT = rectangles, S = dropdown, P = product_list, PI = product_list_with_images, CS = swatch. - enum: - - radio_buttons - - rectangles - - dropdown - - product_list - - product_list_with_images - - swatch - x-required: - - post - - put - config: - title: Option Config - type: object - description: The values for option config can vary based on the Modifier created. - properties: - default_value: - type: string - description: | - (date, text, multi_line_text, numbers_only_text) The default value. Shown on a date option as an ISO-8601–formatted string, or on a text option as a string. - checked_by_default: - type: boolean - description: | - (checkbox) Flag for setting the checkbox to be checked by default. - checkbox_label: - type: string - description: | - (checkbox) Label displayed for the checkbox option. - date_limited: - type: boolean - description: | - (date) Flag to limit the dates allowed to be entered on a date option. - date_limit_mode: - type: string - description: | - (date) The type of limit that is allowed to be entered on a date option. - example: range - enum: - - earliest - - range - - latest - date_earliest_value: - type: string - description: | - (date) The earliest date allowed to be entered on the date option, as an ISO-8601 formatted string. - format: date-time - example: '2018-08-31T00:00:00+00:00' - date_latest_value: - type: string - description: | - (date) The latest date allowed to be entered on the date option, as an ISO-8601 formatted string. - format: date-time - example: '2019-01-01T00:00:00+00:00' - file_types_mode: - type: string - description: | - (file) The kind of restriction on the file types that can be uploaded with a file upload option. Values: `specific` - restricts uploads to particular file types; `all` - allows all file types. - example: specific - enum: - - specific - - all - file_types_supported: - type: array - description: | - (file) The type of files allowed to be uploaded if the `file_type_option` is set to `specific`. Values: - `images` - Allows upload of image MIME types (`bmp`, `gif`, `jpg`, `jpeg`, `jpe`, `jif`, `jfif`, `jfi`, `png`, `wbmp`, `xbm`, `tiff`). `documents` - Allows upload of document MIME types (`txt`, `pdf`, `rtf`, `doc`, `docx`, `xls`, `xlsx`, `accdb`, `mdb`, `one`, `pps`, `ppsx`, `ppt`, `pptx`, `pub`, `odt`, `ods`, `odp`, `odg`, `odf`). - `other` - Allows file types defined in the `file_types_other` array. - example: - - images - - documents - - other - items: - type: string - file_types_other: - type: array - description: | - (file) A list of other file types allowed with the file upload option. - example: - - pdf - - txt - items: - type: string - file_max_size: - type: integer - description: | - (file) The maximum size for a file that can be used with the file upload option. This will still be limited by the server. - example: 5 - text_characters_limited: - type: boolean - description: | - (text, multi_line_text) Flag to validate the length of a text or multi-line text input. - text_min_length: - type: integer - description: | - (text, multi_line_text) The minimum length allowed for a text or multi-line text option. - example: 1 - text_max_length: - type: integer - description: | - (text, multi_line_text) The maximum length allowed for a text or multi line text option. - example: 55 - text_lines_limited: - type: boolean - description: | - (multi_line_text) Flag to validate the maximum number of lines allowed on a multi-line text input. - example: true - text_max_lines: - type: integer - description: | - (multi_line_text) The maximum number of lines allowed on a multi-line text input. - example: 4 - number_limited: - type: boolean - description: | - (numbers_only_text) Flag to limit the value of a number option. - example: true - number_limit_mode: - type: string - description: | - (numbers_only_text) The type of limit on values entered for a number option. - example: lowest - enum: - - lowest - - highest - - range - number_lowest_value: - type: number - description: | - (numbers_only_text) The lowest allowed value for a number option if `number_limited` is true. - example: 100 - number_highest_value: - type: number - description: | - (numbers_only_text) The highest allowed value for a number option if `number_limited` is true. - number_integers_only: - type: boolean - description: | - (numbers_only_text) Flag to limit the input on a number option to whole numbers only. - example: false - product_list_adjusts_inventory: - type: boolean - description: | - (product_list, product_list_with_images) Flag for automatically adjusting inventory on a product included in the list. - product_list_adjusts_pricing: - type: boolean - description: | - (product_list, product_list_with_images) Flag to add the optional product's price to the main product's price. - product_list_shipping_calc: - type: string - description: | - (product_list, product_list_with_images) How to factor the optional product's weight and package dimensions into the shipping quote. Values: `none` - don't adjust; `weight` - use shipping weight only; `package` - use weight and dimensions. - example: weight - enum: - - none - - weight - - package - sort_order: - type: integer - description: 'Order in which the option is displayed on the storefront. ' - example: 1 - option_values: - minItems: 1 - type: array - x-required: - - post - - put - items: - title: Option Value - allOf: - - title: Option Value Base - description: Common Option Value properties. - properties: - is_default: - type: boolean - description: | - The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. - example: false - label: - type: string - description: | - The text display identifying the value on the storefront. Required in a /POST. - example: Green - x-required: - - post - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the value will be displayed on the product page. Required in a /POST. - example: 0 - x-required: - - post - value_data: - type: object - properties: {} - description: | - Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. - required: - - label - - sort_order - - properties: - id: - type: integer - description: | - The unique numeric ID of the value; increments sequentially. - type: object - image_url: - type: string - description: Publicly available image url - type: object - required: true - responses: - '200': - description: '' - content: - application/json: - schema: - title: Option Response - type: object - properties: - data: - title: Option - type: object - allOf: - - title: Option Base - description: Common Option properties. - type: object - properties: - id: - type: integer - description: | - The unique numerical ID of the option, increments sequentially. - example: 55 - x-nullable: true - product_id: - type: integer - description: | - The unique numerical ID of the product to which the option belongs. - example: 4 - x-required: - - post - - put - display_name: - maxLength: 255 - minLength: 1 - type: string - description: | - The name of the option shown on the storefront. - example: Add-a-$5-Donation1535042499-187 - x-required: - - post - - put - type: - type: string - description: | - The type of option, which determines how it will display on the storefront. Acceptable values: `radio_buttons`, `rectangles`, `dropdown`, `product_list`, `product_list_with_images`, `swatch`. For reference, the former v2 API values are: RB = radio_buttons, RT = rectangles, S = dropdown, P = product_list, PI = product_list_with_images, CS = swatch. - enum: - - radio_buttons - - rectangles - - dropdown - - product_list - - product_list_with_images - - swatch - x-required: - - post - - put - config: - title: Option Config - type: object - description: The values for option config can vary based on the Modifier created. - properties: - default_value: - type: string - description: | - (date, text, multi_line_text, numbers_only_text) The default value. Shown on a date option as an ISO-8601–formatted string, or on a text option as a string. - checked_by_default: - type: boolean - description: | - (checkbox) Flag for setting the checkbox to be checked by default. - checkbox_label: - type: string - description: | - (checkbox) Label displayed for the checkbox option. - date_limited: - type: boolean - description: | - (date) Flag to limit the dates allowed to be entered on a date option. - date_limit_mode: - type: string - description: | - (date) The type of limit that is allowed to be entered on a date option. - example: range - enum: - - earliest - - range - - latest - date_earliest_value: - type: string - description: | - (date) The earliest date allowed to be entered on the date option, as an ISO-8601 formatted string. - format: date-time - date_latest_value: - type: string - description: | - (date) The latest date allowed to be entered on the date option, as an ISO-8601 formatted string. - format: date-time - file_types_mode: - type: string - description: | - (file) The kind of restriction on the file types that can be uploaded with a file upload option. Values: `specific` - restricts uploads to particular file types; `all` - allows all file types. - example: specific - enum: - - specific - - all - file_types_supported: - type: array - description: | - (file) The type of files allowed to be uploaded if the `file_type_option` is set to `specific`. Values: - `images` - Allows upload of image MIME types (`bmp`, `gif`, `jpg`, `jpeg`, `jpe`, `jif`, `jfif`, `jfi`, `png`, `wbmp`, `xbm`, `tiff`). `documents` - Allows upload of document MIME types (`txt`, `pdf`, `rtf`, `doc`, `docx`, `xls`, `xlsx`, `accdb`, `mdb`, `one`, `pps`, `ppsx`, `ppt`, `pptx`, `pub`, `odt`, `ods`, `odp`, `odg`, `odf`). - `other` - Allows file types defined in the `file_types_other` array. - items: - type: string - example: 'images, documents, other' - file_types_other: - type: array - description: | - (file) A list of other file types allowed with the file upload option. - items: - type: string - example: pdf - file_max_size: - type: integer - description: | - (file) The maximum size for a file that can be used with the file upload option. This will still be limited by the server. - example: 5 - text_characters_limited: - type: boolean - description: | - (text, multi_line_text) Flag to validate the length of a text or multi-line text input. - text_min_length: - type: integer - description: | - (text, multi_line_text) The minimum length allowed for a text or multi-line text option. - example: 1 - text_max_length: - type: integer - description: | - (text, multi_line_text) The maximum length allowed for a text or multi line text option. - example: 55 - text_lines_limited: - type: boolean - description: | - (multi_line_text) Flag to validate the maximum number of lines allowed on a multi-line text input. - example: true - text_max_lines: - type: integer - description: | - (multi_line_text) The maximum number of lines allowed on a multi-line text input. - example: 4 - number_limited: - type: boolean - description: | - (numbers_only_text) Flag to limit the value of a number option. - example: true - number_limit_mode: - type: string - description: | - (numbers_only_text) The type of limit on values entered for a number option. - example: lowest - enum: - - lowest - - highest - - range - number_lowest_value: - type: number - description: | - (numbers_only_text) The lowest allowed value for a number option if `number_limited` is true. - example: 100 - number_highest_value: - type: number - description: | - (numbers_only_text) The highest allowed value for a number option if `number_limited` is true. - number_integers_only: - type: boolean - description: | - (numbers_only_text) Flag to limit the input on a number option to whole numbers only. - example: false - product_list_adjusts_inventory: - type: boolean - description: | - (product_list, product_list_with_images) Flag for automatically adjusting inventory on a product included in the list. - product_list_adjusts_pricing: - type: boolean - description: | - (product_list, product_list_with_images) Flag to add the optional product's price to the main product's price. - product_list_shipping_calc: - type: string - description: | - (product_list, product_list_with_images) How to factor the optional product's weight and package dimensions into the shipping quote. Values: `none` - don't adjust; `weight` - use shipping weight only; `package` - use weight and dimensions. - example: weight - enum: - - none - - weight - - package - sort_order: - type: integer - description: 'Order in which the option is displayed on the storefront. ' - example: 1 - option_values: - minItems: 1 - type: array - x-required: - - post - - put - items: - title: Option Value - allOf: - - title: Option Value Base - description: Common Option Value properties. - properties: - is_default: - type: boolean - description: | - The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. - example: false - label: - type: string - description: | - The text display identifying the value on the storefront. Required in a /POST. - example: Green - x-required: - - post - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the value will be displayed on the product page. Required in a /POST. - example: 0 - x-required: - - post - value_data: - type: object - properties: {} - description: | - Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. - required: - - label - - sort_order - - properties: - id: - type: integer - description: | - The unique numeric ID of the value; increments sequentially. - type: object - image_url: - type: string - description: Publicly available image url - - type: object - properties: - name: - type: string - description: | - The unique option name, auto-generated from the display name, a timestamp, and the product ID. - example: Add-a-$5-Donation1535042499-187 - meta: - title: Meta - type: object - properties: {} - description: Empty meta object; may be used later. - examples: - example-1: - value: - data: - id: 55 - product_id: 4 - display_name: Add-a-$5-Donation1535042499-187 - type: radio_buttons - config: - default_value: string - checked_by_default: true - checkbox_label: string - date_limited: true - date_limit_mode: earliest - date_earliest_value: '2022-08-24T00:00:00+00:00' - date_latest_value: '2022-08-27T00:00:00+00:00' - file_types_mode: specific - file_types_supported: - - 'images, documents, other' - file_types_other: - - pdf - file_max_size: 5 - text_characters_limited: true - text_min_length: 1 - text_max_length: 55 - text_lines_limited: true - text_max_lines: 4 - number_limited: true - number_limit_mode: lowest - number_lowest_value: 100 - number_highest_value: 0 - number_integers_only: false - product_list_adjusts_inventory: true - product_list_adjusts_pricing: true - product_list_shipping_calc: none - sort_order: 1 - option_values: - - is_default: false - label: Green - sort_order: 0 - value_data: {} - id: 0 - image_url: string - name: Add-a-$5-Donation1535042499-187 - meta: {} - example-2: - value: - data: - id: 220 - product_id: 192 - name: Color (Colors only) - display_name: Color - type: swatch - sort_order: 0 - option_values: - - id: 174 - label: Beige - sort_order: 1 - value_data: - colors: - - '#FAFAEB' - is_default: false - - id: 175 - label: Grey - sort_order: 2 - value_data: - colors: - - '#BDBDBD' - is_default: false - - id: 176 - label: Black - sort_order: 3 - value_data: - colors: - - '#000000' - is_default: false - - id: 189 - label: Black-Walnut - sort_order: 4 - value_data: - colors: - - '#e80ee8' - is_default: false - config: {} - meta: {} - '409': - description: | - Option was in conflict with another option. This is the result of duplicate unique fields, such as `name`. - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - '422': - description: | - Option was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - x-codegen-request-body-name: Option - parameters: - - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/ProductIdParam' - '/catalog/products/{product_id}/options/{option_id}': - get: - tags: - - Product Variant Options - summary: Get a Product Variant Option - description: Returns a single *Variant Option*. Optional parameters can be passed in. - operationId: getOptionById - parameters: - - name: option_id - in: path - description: | - The ID of the `Option`. - required: true - schema: - type: integer - - - name: include_fields - in: query - description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' - schema: - type: string - - name: exclude_fields - in: query - description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' - schema: - type: string - responses: - '200': - description: '' - content: - application/json: - schema: - title: Option Response - type: object - properties: - data: - $ref: '#/components/schemas/productOption_Full' - meta: - $ref: '#/components/schemas/metaEmpty_Full' - '404': - description: | - The resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - put: - tags: - - Product Variant Options - summary: Update a Product Variant Option - description: |- - Updates a *Variant Option*. - - **Read-Only Fields** - * id - operationId: updateOption - parameters: - - $ref: '#/components/parameters/ContentType' - - name: option_id - in: path - description: | - The ID of the `Option`. - required: true - schema: - type: integer - requestBody: - content: - application/json: - schema: - title: Option Put - description: The model for a PUT to update options on a product. - allOf: - - title: Option Base - type: object - properties: - id: - type: integer - description: | - The unique numerical ID of the option, increments sequentially. - nullable: true - example: 55 - product_id: - type: integer - description: | - The unique numerical ID of the product to which the option belongs. - example: 4 - x-required: - - post - - put - display_name: - maxLength: 255 - minLength: 1 - type: string - description: | - The name of the option shown on the storefront. - example: Add-a-$5-Donation1535042499-187 - x-required: - - post - - put - type: - type: string - description: | - The type of option, which determines how it will display on the storefront. Acceptable values: `radio_buttons`, `rectangles`, `dropdown`, `product_list`, `product_list_with_images`, `swatch`. For reference, the former v2 API values are: RB = radio_buttons, RT = rectangles, S = dropdown, P = product_list, PI = product_list_with_images, CS = swatch. - enum: - - radio_buttons - - rectangles - - dropdown - - product_list - - product_list_with_images - - swatch - x-required: - - post - - put - config: - title: Option Config - type: object - properties: - default_value: - type: string - description: | - (date, text, multi_line_text, numbers_only_text) The default value. Shown on a date option as an ISO-8601–formatted string, or on a text option as a string. - checked_by_default: - type: boolean - description: | - (checkbox) Flag for setting the checkbox to be checked by default. - checkbox_label: - type: string - description: | - (checkbox) Label displayed for the checkbox option. - date_limited: - type: boolean - description: | - (date) Flag to limit the dates allowed to be entered on a date option. - date_limit_mode: - type: string - description: | - (date) The type of limit that is allowed to be entered on a date option. - example: range - enum: - - earliest - - range - - latest - date_earliest_value: - type: string - description: | - (date) The earliest date allowed to be entered on the date option, as an ISO-8601 formatted string. - format: date-time - example: '2018-08-31T00:00:00+00:00' - date_latest_value: - type: string - description: | - (date) The latest date allowed to be entered on the date option, as an ISO-8601 formatted string. - format: date-time - example: '2019-01-01T00:00:00+00:00' - file_types_mode: - type: string - description: | - (file) The kind of restriction on the file types that can be uploaded with a file upload option. Values: `specific` - restricts uploads to particular file types; `all` - allows all file types. - example: specific - enum: - - specific - - all - file_types_supported: - type: array - description: | - (file) The type of files allowed to be uploaded if the `file_type_option` is set to `specific`. Values: - `images` - Allows upload of image MIME types (`bmp`, `gif`, `jpg`, `jpeg`, `jpe`, `jif`, `jfif`, `jfi`, `png`, `wbmp`, `xbm`, `tiff`). `documents` - Allows upload of document MIME types (`txt`, `pdf`, `rtf`, `doc`, `docx`, `xls`, `xlsx`, `accdb`, `mdb`, `one`, `pps`, `ppsx`, `ppt`, `pptx`, `pub`, `odt`, `ods`, `odp`, `odg`, `odf`). - `other` - Allows file types defined in the `file_types_other` array. - example: - - images - - documents - - other - items: - type: string - file_types_other: - type: array - description: | - (file) A list of other file types allowed with the file upload option. - example: - - pdf - - txt - items: - type: string - file_max_size: - type: integer - description: | - (file) The maximum size for a file that can be used with the file upload option. This will still be limited by the server. - example: 5 - text_characters_limited: - type: boolean - description: | - (text, multi_line_text) Flag to validate the length of a text or multi-line text input. - text_min_length: - type: integer - description: | - (text, multi_line_text) The minimum length allowed for a text or multi-line text option. - example: 1 - text_max_length: - type: integer - description: | - (text, multi_line_text) The maximum length allowed for a text or multi line text option. - example: 55 - text_lines_limited: - type: boolean - description: | - (multi_line_text) Flag to validate the maximum number of lines allowed on a multi-line text input. - example: true - text_max_lines: - type: integer - description: | - (multi_line_text) The maximum number of lines allowed on a multi-line text input. - example: 4 - number_limited: - type: boolean - description: | - (numbers_only_text) Flag to limit the value of a number option. - example: true - number_limit_mode: - type: string - description: | - (numbers_only_text) The type of limit on values entered for a number option. - example: lowest - enum: - - lowest - - highest - - range - number_lowest_value: - type: number - description: | - (numbers_only_text) The lowest allowed value for a number option if `number_limited` is true. - example: 100 - number_highest_value: - type: number - description: | - (numbers_only_text) The highest allowed value for a number option if `number_limited` is true. - number_integers_only: - type: boolean - description: | - (numbers_only_text) Flag to limit the input on a number option to whole numbers only. - example: false - product_list_adjusts_inventory: - type: boolean - description: | - (product_list, product_list_with_images) Flag for automatically adjusting inventory on a product included in the list. - product_list_adjusts_pricing: - type: boolean - description: | - (product_list, product_list_with_images) Flag to add the optional product's price to the main product's price. - product_list_shipping_calc: - type: string - description: | - (product_list, product_list_with_images) How to factor the optional product's weight and package dimensions into the shipping quote. Values: `none` - don't adjust; `weight` - use shipping weight only; `package` - use weight and dimensions. - example: weight - enum: - - none - - weight - - package - description: The values for option config can vary based on the Modifier created. - sort_order: - type: integer - description: 'Order in which the option is displayed on the storefront. ' - example: 1 - option_values: - minItems: 1 - type: array - items: - title: Option Value - type: object - allOf: - - title: Option Value Base - required: - - label - - sort_order - type: object - properties: - is_default: - type: boolean - description: | - The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. - example: false - label: - type: string - description: | - The text display identifying the value on the storefront. Required in a /POST. - example: Green - x-required: - - post - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the value will be displayed on the product page. Required in a /POST. - example: 0 - x-required: - - post - value_data: - type: object - properties: {} - description: | - Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. - description: Common Option Value properties. - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the value; increments sequentially. - x-required: - - post - - put - image_url: - type: string - description: Publicly available image url - description: Common Option properties. - required: true - responses: - '200': - description: '' - content: - application/json: - schema: - title: Option Response - type: object - properties: - data: - title: Option - type: object - allOf: - - title: Option Base - type: object - properties: - id: - type: integer - description: | - The unique numerical ID of the option, increments sequentially. - example: 55 - x-nullable: true - product_id: - type: integer - description: | - The unique numerical ID of the product to which the option belongs. - example: 4 - x-required: - - post - - put - display_name: - maxLength: 255 - minLength: 1 - type: string - description: | - The name of the option shown on the storefront. - example: Add-a-$5-Donation1535042499-187 - x-required: - - post - - put - type: - type: string - description: | - The type of option, which determines how it will display on the storefront. Acceptable values: `radio_buttons`, `rectangles`, `dropdown`, `product_list`, `product_list_with_images`, `swatch`. For reference, the former v2 API values are: RB = radio_buttons, RT = rectangles, S = dropdown, P = product_list, PI = product_list_with_images, CS = swatch. - enum: - - radio_buttons - - rectangles - - dropdown - - product_list - - product_list_with_images - - swatch - x-required: - - post - - put - config: - title: Option Config - type: object - properties: - default_value: - type: string - description: | - (date, text, multi_line_text, numbers_only_text) The default value. Shown on a date option as an ISO-8601–formatted string, or on a text option as a string. - checked_by_default: - type: boolean - description: | - (checkbox) Flag for setting the checkbox to be checked by default. - checkbox_label: - type: string - description: | - (checkbox) Label displayed for the checkbox option. - date_limited: - type: boolean - description: | - (date) Flag to limit the dates allowed to be entered on a date option. - date_limit_mode: - type: string - description: | - (date) The type of limit that is allowed to be entered on a date option. - example: range - enum: - - earliest - - range - - latest - date_earliest_value: - type: string - description: | - (date) The earliest date allowed to be entered on the date option, as an ISO-8601 formatted string. - format: date - date_latest_value: - type: string - description: | - (date) The latest date allowed to be entered on the date option, as an ISO-8601 formatted string. - format: date - file_types_mode: - type: string - description: | - (file) The kind of restriction on the file types that can be uploaded with a file upload option. Values: `specific` - restricts uploads to particular file types; `all` - allows all file types. - example: specific - enum: - - specific - - all - file_types_supported: - type: array - description: | - (file) The type of files allowed to be uploaded if the `file_type_option` is set to `specific`. Values: - `images` - Allows upload of image MIME types (`bmp`, `gif`, `jpg`, `jpeg`, `jpe`, `jif`, `jfif`, `jfi`, `png`, `wbmp`, `xbm`, `tiff`). `documents` - Allows upload of document MIME types (`txt`, `pdf`, `rtf`, `doc`, `docx`, `xls`, `xlsx`, `accdb`, `mdb`, `one`, `pps`, `ppsx`, `ppt`, `pptx`, `pub`, `odt`, `ods`, `odp`, `odg`, `odf`). - `other` - Allows file types defined in the `file_types_other` array. - items: - type: string - example: 'images, documents, other' - file_types_other: - type: array - description: | - (file) A list of other file types allowed with the file upload option. - items: - type: string - example: pdf - file_max_size: - type: integer - description: | - (file) The maximum size for a file that can be used with the file upload option. This will still be limited by the server. - example: 5 - text_characters_limited: - type: boolean - description: | - (text, multi_line_text) Flag to validate the length of a text or multi-line text input. - text_min_length: - type: integer - description: | - (text, multi_line_text) The minimum length allowed for a text or multi-line text option. - example: 1 - text_max_length: - type: integer - description: | - (text, multi_line_text) The maximum length allowed for a text or multi line text option. - example: 55 - text_lines_limited: - type: boolean - description: | - (multi_line_text) Flag to validate the maximum number of lines allowed on a multi-line text input. - example: true - text_max_lines: - type: integer - description: | - (multi_line_text) The maximum number of lines allowed on a multi-line text input. - example: 4 - number_limited: - type: boolean - description: | - (numbers_only_text) Flag to limit the value of a number option. - example: true - number_limit_mode: - type: string - description: | - (numbers_only_text) The type of limit on values entered for a number option. - example: lowest - enum: - - lowest - - highest - - range - number_lowest_value: - type: number - description: | - (numbers_only_text) The lowest allowed value for a number option if `number_limited` is true. - example: 100 - number_highest_value: - type: number - description: | - (numbers_only_text) The highest allowed value for a number option if `number_limited` is true. - number_integers_only: - type: boolean - description: | - (numbers_only_text) Flag to limit the input on a number option to whole numbers only. - example: false - product_list_adjusts_inventory: - type: boolean - description: | - (product_list, product_list_with_images) Flag for automatically adjusting inventory on a product included in the list. - product_list_adjusts_pricing: - type: boolean - description: | - (product_list, product_list_with_images) Flag to add the optional product's price to the main product's price. - product_list_shipping_calc: - type: string - description: | - (product_list, product_list_with_images) How to factor the optional product's weight and package dimensions into the shipping quote. Values: `none` - don't adjust; `weight` - use shipping weight only; `package` - use weight and dimensions. - example: weight - enum: - - none - - weight - - package - description: The values for option config can vary based on the Modifier created. - sort_order: - type: integer - description: 'Order in which the option is displayed on the storefront. ' - example: 1 - option_values: - minItems: 1 - type: array - items: - title: Option Value - type: object - allOf: - - title: Option Value Base - required: - - label - - sort_order - type: object - properties: - is_default: - type: boolean - description: | - The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. - example: false - label: - type: string - description: | - The text display identifying the value on the storefront. Required in a /POST. - example: Green - x-required: - - post - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the value will be displayed on the product page. Required in a /POST. - example: 0 - x-required: - - post - value_data: - type: object - properties: {} - description: | - Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. - x-nullable: true - description: Common Option Value properties. - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the value; increments sequentially. - x-required: - - post - - put - image_url: - type: string - description: Publicly available image url - description: Common Option properties. - - type: object - properties: - name: - type: string - description: | - The unique option name, auto-generated from the display name, a timestamp, and the product ID. - example: Add-a-$5-Donation1535042499-187 - meta: - $ref: '#/components/schemas/metaEmpty_Full' - example: - data: - id: 220 - product_id: 192 - name: Color (Colors only) - display_name: Color - type: swatch - sort_order: 0 - option_values: - - id: 174 - label: Beige - sort_order: 1 - value_data: - colors: - - '#FAFAEB' - is_default: false - - id: 175 - label: Grey - sort_order: 2 - value_data: - colors: - - '#BDBDBD' - is_default: false - - id: 176 - label: Black - sort_order: 3 - value_data: - colors: - - '#000000' - is_default: false - - id: 189 - label: Black-Walnut - sort_order: 4 - value_data: - colors: - - '#e80ee8' - is_default: false - config: {} - meta: {} - '409': - description: | - The `Option` was in conflict with another option. This is the result of duplicate unique fields, such as `name`. - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - '422': - description: | - The `Option` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - x-codegen-request-body-name: option - delete: - tags: - - Product Variant Options - summary: Delete a Product Variant Option - description: Deletes a *Variant Option*. - operationId: deleteOptionById - parameters: - - name: option_id - in: path - description: | - The ID of the `Option`. - required: true - schema: - type: integer - responses: - '204': - description: '' - content: {} - parameters: - - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/ProductIdParam' - - $ref: '#/components/parameters/OptionIdParam' - '/catalog/products/{product_id}/options/{option_id}/values': - get: - tags: - - Product Variant Option Values - summary: Get All Product Variant Option Values - description: Returns a list of all *Variant Option Values*. Optional parameters can be passed in. - operationId: getOptionValues - parameters: - - name: option_id - in: path - description: | - The ID of the `Option`. - required: true - schema: - type: integer - - - name: include_fields - in: query - description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' - schema: - type: string - - name: exclude_fields - in: query - description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' - schema: - type: string - - name: page - in: query - description: Specifies the page number in a limited (paginated) list of products. - schema: - type: integer - - name: limit - in: query - description: Controls the number of items per page in a limited (paginated) list of products. - schema: - type: integer - responses: - '200': - description: '' - content: - application/json: - schema: - title: Option Value Collection Response - type: object - properties: - data: - type: array - items: - title: Option Value - type: object - allOf: - - title: Option Value Base - required: - - label - - sort_order - type: object - properties: - is_default: - type: boolean - description: | - The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. - example: false - label: - type: string - description: | - The text display identifying the value on the storefront. Required in a /POST. - example: Green - x-required: - - post - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the value will be displayed on the product page. Required in a /POST. - example: 0 - x-required: - - post - value_data: - type: object - properties: {} - description: | - Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. - x-nullable: true - description: Common Option Value properties. - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the value; increments sequentially. - meta: - $ref: '#/components/schemas/metaCollection_Full' - description: Get Option Values response. - example: - data: - - id: 174 - label: Beige - sort_order: 1 - value_data: - colors: - - '#FAFAEB' - is_default: false - - id: 175 - label: Grey - sort_order: 2 - value_data: - colors: - - '#BDBDBD' - is_default: false - - id: 176 - label: Black - sort_order: 3 - value_data: - colors: - - '#000000' - is_default: false - - id: 189 - label: Black-Walnut - sort_order: 4 - value_data: - colors: - - '#e80ee8' - is_default: false - meta: - pagination: - total: 4 - count: 4 - per_page: 50 - current_page: 1 - total_pages: 1 - links: - current: '?page=1&limit=50' - post: - tags: - - Product Variant Option Values - summary: Create a Product Variant Option Value - description: |- - Creates a *Variant Option Value*. - - **Required Fields** - * label - * sort_order - - **Read-Only Fields** - * id - - **Limits** - * 250 option values per option limit. - operationId: createOptionValue - parameters: - - $ref: '#/components/parameters/ContentType' - - name: option_id - in: path - description: | - The ID of the `Option`. - required: true - schema: - type: integer - requestBody: - content: - application/json: - schema: - title: Option Value Post - description: The model for a POST to create option values on a product. - allOf: - - title: Option Value Base - required: - - label - - sort_order - type: object - properties: - is_default: - type: boolean - description: | - The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. - example: false - label: - type: string - description: | - The text display identifying the value on the storefront. Required in a /POST. - example: Green - x-required: - - post - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the value will be displayed on the product page. Required in a /POST. - example: 0 - x-required: - - post - value_data: - type: object - properties: {} - description: | - Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. - description: Common Option Value properties. - required: true - responses: - '200': - description: '' - content: - application/json: - schema: - title: Option Value Response - type: object - properties: - data: - title: Option Value - type: object - allOf: - - title: Option Value Base - required: - - label - - sort_order - type: object - properties: - is_default: - type: boolean - description: | - The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. - example: false - label: - type: string - description: | - The text display identifying the value on the storefront. Required in a /POST. - example: Green - x-required: - - post - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the value will be displayed on the product page. Required in a /POST. - example: 0 - x-required: - - post - value_data: - type: object - properties: {} - description: | - Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. - x-nullable: true - description: Common Option Value properties. - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the value; increments sequentially. - meta: - $ref: '#/components/schemas/metaEmpty_Full' - example: - data: - id: 44 - label: Pick a color - sort_order: 9 - value_data: - colors: - - '#123c91, #FFFF00, #397a44' - is_default: false - '422': - description: | - The `OptionValue` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - x-codegen-request-body-name: OptionValue - parameters: - - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/ProductIdParam' - - $ref: '#/components/parameters/OptionIdParam' - '/catalog/products/{product_id}/options/{option_id}/values/{value_id}': - get: - tags: - - Product Variant Option Values - summary: Get a Product Variant Option Value - description: Returns a single *Variant Option Value*. Optional parameters can be passed in. - operationId: getOptionValueById - parameters: - - name: option_id - in: path - description: | - The ID of the `Option`. - required: true - schema: - type: integer - - name: value_id - in: path - description: | - The ID of the `Modifier/Option Value`. - required: true - schema: - type: integer - - - name: include_fields - in: query - description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' - schema: - type: string - - name: exclude_fields - in: query - description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' - schema: - type: string - responses: - '200': - description: '' - content: - application/json: - schema: - title: Option Value Response - type: object - properties: - data: - title: Option Value - type: object - allOf: - - title: Option Value Base - required: - - label - - sort_order - type: object - properties: - is_default: - type: boolean - description: | - The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. - example: false - label: - type: string - description: | - The text display identifying the value on the storefront. Required in a /POST. - example: Green - x-required: - - post - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the value will be displayed on the product page. Required in a /POST. - example: 0 - x-required: - - post - value_data: - type: object - properties: {} - description: | - Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. - x-nullable: true - description: Common Option Value properties. - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the value; increments sequentially. - meta: - $ref: '#/components/schemas/metaEmpty_Full' - example: - data: - id: 44 - label: Pick a color - sort_order: 9 - value_data: - colors: - - '#123c91, #FFFF00, #397a44' - is_default: false - '404': - description: | - The resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - put: - tags: - - Product Variant Option Values - summary: Update a Product Variant Option Value - description: |- - Updates a *Variant Option Value*. - - **Read-Only Fields** - * id - operationId: updateOptionValue - parameters: - - $ref: '#/components/parameters/ContentType' - - name: option_id - in: path - description: | - The ID of the `Option`. - required: true - schema: - type: integer - - name: value_id - in: path - description: | - The ID of the `Modifier/Option Value`. - required: true - schema: - type: integer - requestBody: - description: | - A BigCommerce `OptionValue` object. - content: - application/json: - schema: - title: Option Value Put - description: The model for a PUT to update option values on a product. - allOf: - - title: Option Value Base - required: - - label - - sort_order - type: object - properties: - is_default: - type: boolean - description: | - The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. - example: false - label: - type: string - description: | - The text display identifying the value on the storefront. Required in a /POST. - example: Green - x-required: - - post - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the value will be displayed on the product page. Required in a /POST. - example: 0 - x-required: - - post - value_data: - type: object - properties: {} - description: | - Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. - description: Common Option Value properties. - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the value; increments sequentially. - x-required: - - put - required: true - responses: - '200': - description: '' - content: - application/json: - schema: - title: Option Value Response - type: object - properties: - data: - title: Option Value - type: object - allOf: - - title: Option Value Base - required: - - label - - sort_order - type: object - properties: - is_default: - type: boolean - description: | - The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. - example: false - label: - type: string - description: | - The text display identifying the value on the storefront. Required in a /POST. - example: Green - x-required: - - post - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the value will be displayed on the product page. Required in a /POST. - example: 0 - x-required: - - post - value_data: - type: object - properties: {} - description: | - Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. - x-nullable: true - description: Common Option Value properties. - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the value; increments sequentially. - meta: - $ref: '#/components/schemas/metaEmpty_Full' - example: - data: - id: 44 - label: Pick a color - sort_order: 9 - value_data: - colors: - - '#123c91, #FFFF00, #397a44' - is_default: false - '404': - description: No option(s) were found with this query. - content: {} - '422': - description: | - The `OptionValue` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - x-codegen-request-body-name: OptionValue - delete: - tags: - - Product Variant Option Values - summary: Delete a Product Variant Option Value - description: Deletes a *Variant Option Value*. - operationId: deleteOptionValueById - parameters: - - name: option_id - in: path - description: | - The ID of the `Option`. - required: true - schema: - type: integer - - name: value_id - in: path - description: | - The ID of the `Modifier/Option Value`. - required: true - schema: - type: integer - responses: - '204': - description: '' - content: {} - parameters: - - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/ProductIdParam' - - $ref: '#/components/parameters/OptionIdParam' - - $ref: '#/components/parameters/ValueIdParam' - '/catalog/products/{product_id}/modifiers': - get: - tags: - - Product Modifiers - summary: Get All Product Modifiers - description: Returns a list of all *Product Modifiers*. Optional parameters can be passed in. - operationId: getModifiers - parameters: - - name: page - in: query - description: Specifies the page number in a limited (paginated) list of products. - schema: - type: integer - - name: limit - in: query - description: Controls the number of items per page in a limited (paginated) list of products. - schema: - type: integer - - name: include_fields - in: query - description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' - schema: - type: string - - name: exclude_fields - in: query - description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' - schema: - type: string - responses: - '200': - description: '' - content: - application/json: - schema: - title: Modifier Collection Response - type: object - properties: - data: - type: array - items: - $ref: '#/components/schemas/productModifier_Full' - meta: - $ref: '#/components/schemas/metaCollection_Full' - description: Modifier Collection Response return for /GET All Modifiers. - example: - data: - - id: 206 - product_id: 158 - name: Insurance - display_name: Insurace - type: checkbox - required: true - config: - checkbox_label: $5 for insurance - checked_by_default: false - option_values: - - id: 183 - option_id: 206 - label: 'Yes' - sort_order: 0 - value_data: - checked_value: true - is_default: false - adjusters: - price: {} - weight: {} - image_url: '' - purchasing_disabled: - status: false - message: '' - - id: 184 - option_id: 206 - label: 'No' - sort_order: 1 - value_data: - checked_value: false - is_default: true - adjusters: - price: {} - weight: {} - image_url: '' - purchasing_disabled: - status: false - message: '' - meta: - pagination: - total: 1 - count: 1 - per_page: 50 - current_page: 1 - total_pages: 1 - links: - current: '?page=1&limit=50' - post: - tags: - - Product Modifiers - summary: Create a Product Modifier - description: |- - Creates a *Product Modifier*. - - **Required Fields** - * `required` - * `display_name` - * `type` - - **Read-Only Fields** - * `id` - - **Notes** - It takes two separate requests to create a new checkbox modifier with option values. Perform a request to create a modifier, then perform a second request to update option values. - operationId: createModifier - parameters: - - $ref: '#/components/parameters/ContentType' - requestBody: - content: - application/json: - schema: - title: Modifier Post - description: The model for a POST to create a modifier on a product. - allOf: - - title: Modifier Base - required: - - required - - type - type: object - properties: - type: - type: string - description: | - BigCommerce API, which determines how it will display on the storefront. Acceptable values: `date`, `checkbox`, `file`, `text`, `multi_line_text`, `numbers_only_text`, `radio_buttons`, `rectangles`, `dropdown`, `product_list`, `product_list_with_images`, `swatch`. Required in a /POST. - enum: - - date - - checkbox - - file - - text - - multi_line_text - - numbers_only_text - - radio_buttons - - rectangles - - dropdown - - product_list - - product_list_with_images - - swatch - x-required: - - post - required: - type: boolean - description: | - Whether or not this modifer is required or not at checkout. Required in a /POST. - x-required: - - post - sort_order: - type: integer - description: The order the modifiers display on the product detail page. - config: - title: Option Config - type: object - properties: - default_value: - type: string - description: | - (date, text, multi_line_text, numbers_only_text) The default value. Shown on a date option as an ISO-8601–formatted string, or on a text option as a string. - checked_by_default: - type: boolean - description: | - (checkbox) Flag for setting the checkbox to be checked by default. - checkbox_label: - type: string - description: | - (checkbox) Label displayed for the checkbox option. - date_limited: - type: boolean - description: | - (date) Flag to limit the dates allowed to be entered on a date option. - date_limit_mode: - type: string - description: | - (date) The type of limit that is allowed to be entered on a date option. - example: range - enum: - - earliest - - range - - latest - date_earliest_value: - type: string - description: | - (date) The earliest date allowed to be entered on the date option, as an ISO-8601 formatted string. - format: date-time - example: '2018-08-31T00:00:00+00:00' - date_latest_value: - type: string - description: | - (date) The latest date allowed to be entered on the date option, as an ISO-8601 formatted string. - format: date-time - example: '2019-01-01T00:00:00+00:00' - file_types_mode: - type: string - description: | - (file) The kind of restriction on the file types that can be uploaded with a file upload option. Values: `specific` - restricts uploads to particular file types; `all` - allows all file types. - example: specific - enum: - - specific - - all - file_types_supported: - type: array - description: | - (file) The type of files allowed to be uploaded if the `file_type_option` is set to `specific`. Values: - `images` - Allows upload of image MIME types (`bmp`, `gif`, `jpg`, `jpeg`, `jpe`, `jif`, `jfif`, `jfi`, `png`, `wbmp`, `xbm`, `tiff`). `documents` - Allows upload of document MIME types (`txt`, `pdf`, `rtf`, `doc`, `docx`, `xls`, `xlsx`, `accdb`, `mdb`, `one`, `pps`, `ppsx`, `ppt`, `pptx`, `pub`, `odt`, `ods`, `odp`, `odg`, `odf`). - `other` - Allows file types defined in the `file_types_other` array. - example: - - images - - documents - - other - items: - type: string - file_types_other: - type: array - description: | - (file) A list of other file types allowed with the file upload option. - example: - - pdf - - txt - items: - type: string - file_max_size: - type: integer - description: | - (file) The maximum size for a file that can be used with the file upload option. This will still be limited by the server. - example: 5 - text_characters_limited: - type: boolean - description: | - (text, multi_line_text) Flag to validate the length of a text or multi-line text input. - text_min_length: - type: integer - description: | - (text, multi_line_text) The minimum length allowed for a text or multi-line text option. - example: 1 - text_max_length: - type: integer - description: | - (text, multi_line_text) The maximum length allowed for a text or multi line text option. - example: 55 - text_lines_limited: - type: boolean - description: | - (multi_line_text) Flag to validate the maximum number of lines allowed on a multi-line text input. - example: true - text_max_lines: - type: integer - description: | - (multi_line_text) The maximum number of lines allowed on a multi-line text input. - example: 4 - number_limited: - type: boolean - description: | - (numbers_only_text) Flag to limit the value of a number option. - example: true - number_limit_mode: - type: string - description: | - (numbers_only_text) The type of limit on values entered for a number option. - example: lowest - enum: - - lowest - - highest - - range - number_lowest_value: - type: number - description: | - (numbers_only_text) The lowest allowed value for a number option if `number_limited` is true. - example: 100 - number_highest_value: - type: number - description: | - (numbers_only_text) The highest allowed value for a number option if `number_limited` is true. - number_integers_only: - type: boolean - description: | - (numbers_only_text) Flag to limit the input on a number option to whole numbers only. - example: false - product_list_adjusts_inventory: - type: boolean - description: | - (product_list, product_list_with_images) Flag for automatically adjusting inventory on a product included in the list. - product_list_adjusts_pricing: - type: boolean - description: | - (product_list, product_list_with_images) Flag to add the optional product's price to the main product's price. - product_list_shipping_calc: - type: string - description: | - (product_list, product_list_with_images) How to factor the optional product's weight and package dimensions into the shipping quote. Values: `none` - don't adjust; `weight` - use shipping weight only; `package` - use weight and dimensions. - example: weight - enum: - - none - - weight - - package - description: The values for option config can vary based on the Modifier created. - option_values: - type: array - items: - title: Modifier Value - type: object - description: 'Part of Modifier Value Response ' - allOf: - - title: Modifier Value Base - type: object - allOf: - - title: Option Value Base - required: - - label - - sort_order - type: object - properties: - is_default: - type: boolean - description: | - The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. - example: false - label: - type: string - description: | - The text display identifying the value on the storefront. Required in a /POST. - example: Green - x-required: - - post - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the value will be displayed on the product page. Required in a /POST. - example: 0 - x-required: - - post - value_data: - type: object - properties: {} - description: | - Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. - description: Common Option Value properties. - - type: object - properties: - adjusters: - type: object - properties: - price: - title: Adjuster - type: object - properties: - adjuster: - type: string - description: | - The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - enum: - - relative - - percentage - x-nullable: true - adjuster_value: - type: number - description: | - The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. - example: 5 - description: Adjuster for Complex Rules. - weight: - title: Adjuster - type: object - properties: - adjuster: - type: string - description: | - The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - enum: - - relative - - percentage - x-nullable: true - adjuster_value: - type: number - description: | - The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. - example: 5 - description: Adjuster for Complex Rules. - image_url: - type: string - description: | - The URL for an image displayed on the storefront when the modifier value is selected.Limit of 8MB per file. - example: 'https://cdn8.bigcommerce.com/s-{{store_hash}}/products/184/images/445/naturalcanvascart2_1024x1024__92347__29648.1534344533.1280.1280.jpg?c=2' - purchasing_disabled: - type: object - properties: - status: - type: boolean - description: | - Flag for whether the modifier value disables purchasing when selected on the storefront. This can be used for temporarily disabling a particular modifier value. - message: - type: string - description: | - The message displayed on the storefront when the purchasing disabled status is `true`. - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the value; increments sequentially. - description: Common Modifier properties. - - required: - - display_name - type: object - properties: - display_name: - type: string - description: | - The name of the option shown on the storefront. - example: Donation - x-required: - - post - required: true - responses: - '200': - description: '' - content: - application/json: - schema: - title: Modifier Response - type: object - properties: - data: - title: Modifer - type: object - description: Product Modifier - allOf: - - title: Modifier Base - required: - - required - - type - type: object - properties: - type: - type: string - description: | - BigCommerce API, which determines how it will display on the storefront. Acceptable values: `date`, `checkbox`, `file`, `text`, `multi_line_text`, `numbers_only_text`, `radio_buttons`, `rectangles`, `dropdown`, `product_list`, `product_list_with_images`, `swatch`. Required in a /POST. - enum: - - date - - checkbox - - file - - text - - multi_line_text - - numbers_only_text - - radio_buttons - - rectangles - - dropdown - - product_list - - product_list_with_images - - swatch - x-required: - - post - required: - type: boolean - description: | - Whether or not this modifer is required or not at checkout. Required in a /POST. - x-required: - - post - sort_order: - type: integer - description: The order the modifiers display on the product detail page. - config: - title: Option Config - type: object - properties: - default_value: - type: string - description: | - (date, text, multi_line_text, numbers_only_text) The default value. Shown on a date option as an ISO-8601–formatted string, or on a text option as a string. - checked_by_default: - type: boolean - description: | - (checkbox) Flag for setting the checkbox to be checked by default. - checkbox_label: - type: string - description: | - (checkbox) Label displayed for the checkbox option. - date_limited: - type: boolean - description: | - (date) Flag to limit the dates allowed to be entered on a date option. - date_limit_mode: - type: string - description: | - (date) The type of limit that is allowed to be entered on a date option. - example: range - enum: - - earliest - - range - - latest - date_earliest_value: - type: string - description: | - (date) The earliest date allowed to be entered on the date option, as an ISO-8601 formatted string. - format: date - date_latest_value: - type: string - description: | - (date) The latest date allowed to be entered on the date option, as an ISO-8601 formatted string. - format: date - file_types_mode: - type: string - description: | - (file) The kind of restriction on the file types that can be uploaded with a file upload option. Values: `specific` - restricts uploads to particular file types; `all` - allows all file types. - example: specific - enum: - - specific - - all - file_types_supported: - type: array - description: | - (file) The type of files allowed to be uploaded if the `file_type_option` is set to `specific`. Values: - `images` - Allows upload of image MIME types (`bmp`, `gif`, `jpg`, `jpeg`, `jpe`, `jif`, `jfif`, `jfi`, `png`, `wbmp`, `xbm`, `tiff`). `documents` - Allows upload of document MIME types (`txt`, `pdf`, `rtf`, `doc`, `docx`, `xls`, `xlsx`, `accdb`, `mdb`, `one`, `pps`, `ppsx`, `ppt`, `pptx`, `pub`, `odt`, `ods`, `odp`, `odg`, `odf`). - `other` - Allows file types defined in the `file_types_other` array. - items: - type: string - example: 'images, documents, other' - file_types_other: - type: array - description: | - (file) A list of other file types allowed with the file upload option. - items: - type: string - example: pdf - file_max_size: - type: integer - description: | - (file) The maximum size for a file that can be used with the file upload option. This will still be limited by the server. - example: 5 - text_characters_limited: - type: boolean - description: | - (text, multi_line_text) Flag to validate the length of a text or multi-line text input. - text_min_length: - type: integer - description: | - (text, multi_line_text) The minimum length allowed for a text or multi-line text option. - example: 1 - text_max_length: - type: integer - description: | - (text, multi_line_text) The maximum length allowed for a text or multi line text option. - example: 55 - text_lines_limited: - type: boolean - description: | - (multi_line_text) Flag to validate the maximum number of lines allowed on a multi-line text input. - example: true - text_max_lines: - type: integer - description: | - (multi_line_text) The maximum number of lines allowed on a multi-line text input. - example: 4 - number_limited: - type: boolean - description: | - (numbers_only_text) Flag to limit the value of a number option. - example: true - number_limit_mode: - type: string - description: | - (numbers_only_text) The type of limit on values entered for a number option. - example: lowest - enum: - - lowest - - highest - - range - number_lowest_value: - type: number - description: | - (numbers_only_text) The lowest allowed value for a number option if `number_limited` is true. - example: 100 - number_highest_value: - type: number - description: | - (numbers_only_text) The highest allowed value for a number option if `number_limited` is true. - number_integers_only: - type: boolean - description: | - (numbers_only_text) Flag to limit the input on a number option to whole numbers only. - example: false - product_list_adjusts_inventory: - type: boolean - description: | - (product_list, product_list_with_images) Flag for automatically adjusting inventory on a product included in the list. - product_list_adjusts_pricing: - type: boolean - description: | - (product_list, product_list_with_images) Flag to add the optional product's price to the main product's price. - product_list_shipping_calc: - type: string - description: | - (product_list, product_list_with_images) How to factor the optional product's weight and package dimensions into the shipping quote. Values: `none` - don't adjust; `weight` - use shipping weight only; `package` - use weight and dimensions. - example: weight - enum: - - none - - weight - - package - description: The values for option config can vary based on the Modifier created. - option_values: - type: array - items: - title: Modifier Value - type: object - description: 'Part of Modifier Value Response ' - allOf: - - title: Modifier Value Base - type: object - allOf: - - title: Option Value Base - required: - - label - - sort_order - type: object - properties: - is_default: - type: boolean - description: | - The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. - example: false - label: - type: string - description: | - The text display identifying the value on the storefront. Required in a /POST. - example: Green - x-required: - - post - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the value will be displayed on the product page. Required in a /POST. - example: 0 - x-required: - - post - value_data: - type: object - properties: {} - description: | - Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. - description: Common Option Value properties. - - type: object - properties: - adjusters: - type: object - properties: - price: - title: Adjuster - type: object - properties: - adjuster: - type: string - description: | - The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - enum: - - relative - - percentage - x-nullable: true - adjuster_value: - type: number - description: | - The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. - example: 5 - description: Adjuster for Complex Rules. - weight: - title: Adjuster - type: object - properties: - adjuster: - type: string - description: | - The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - enum: - - relative - - percentage - x-nullable: true - adjuster_value: - type: number - description: | - The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. - example: 5 - description: Adjuster for Complex Rules. - image_url: - type: string - description: | - The URL for an image displayed on the storefront when the modifier value is selected.Limit of 8MB per file. - example: 'https://cdn8.bigcommerce.com/s-{{store_hash}}/products/184/images/445/naturalcanvascart2_1024x1024__92347__29648.1534344533.1280.1280.jpg?c=2' - purchasing_disabled: - type: object - properties: - status: - type: boolean - description: | - Flag for whether the modifier value disables purchasing when selected on the storefront. This can be used for temporarily disabling a particular modifier value. - message: - type: string - description: | - The message displayed on the storefront when the purchasing disabled status is `true`. - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the value; increments sequentially. - description: Common Modifier properties. - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the modifier; increments sequentially. - example: 12 - product_id: - type: integer - description: | - The unique numeric ID of the product to which the option belongs. - example: 77 - name: - type: string - description: | - The unique option name. Auto-generated from the display name, a timestamp, and the product ID. - example: Add-a-$5-Donation1535039590-191 - display_name: - type: string - description: | - The name of the option shown on the storefront. - example: Donation - meta: - $ref: '#/components/schemas/metaEmpty_Full' - '409': - description: | - The `Modifier` was in conflict with another option. This is the result of duplicate unique fields, such as `name`. - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - '422': - description: | - The `Modifier` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - x-codegen-request-body-name: Modifier - parameters: - - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/ProductIdParam' - '/catalog/products/{product_id}/modifiers/{modifier_id}': - get: - tags: - - Product Modifiers - summary: Get a Modifier - description: Returns a single *Product Modifier*. Optional parameters can be passed in. - operationId: getModifierById - parameters: - - name: modifier_id - in: path - description: | - The ID of the `Modifier`. - required: true - schema: - type: integer - - - name: include_fields - in: query - description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' - schema: - type: string - - name: exclude_fields - in: query - description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' - schema: - type: string - responses: - '200': - description: '' - content: - application/json: - schema: - title: Modifier Response - type: object - properties: - data: - $ref: '#/components/schemas/productModifier_Full' - meta: - $ref: '#/components/schemas/metaEmpty_Full' - '404': - description: | - The resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - put: - tags: - - Product Modifiers - summary: Update a Modifier - description: Updates a *Product Modifier*. - operationId: updateModifier - parameters: - - $ref: '#/components/parameters/ContentType' - - name: modifier_id - in: path - description: | - The ID of the `Modifier`. - required: true - schema: - type: integer - requestBody: - content: - application/json: - schema: - title: Modifier Put - description: The model for a PUT to update a modifier on a product. - allOf: - - title: Modifier Base - required: - - required - - type - type: object - properties: - type: - type: string - description: | - BigCommerce API, which determines how it will display on the storefront. Acceptable values: `date`, `checkbox`, `file`, `text`, `multi_line_text`, `numbers_only_text`, `radio_buttons`, `rectangles`, `dropdown`, `product_list`, `product_list_with_images`, `swatch`. Required in a /POST. - enum: - - date - - checkbox - - file - - text - - multi_line_text - - numbers_only_text - - radio_buttons - - rectangles - - dropdown - - product_list - - product_list_with_images - - swatch - x-required: - - post - required: - type: boolean - description: | - Whether or not this modifer is required or not at checkout. Required in a /POST. - x-required: - - post - sort_order: - type: integer - description: The order the modifiers display on the product detail page. - config: - title: Option Config - type: object - properties: - default_value: - type: string - description: | - (date, text, multi_line_text, numbers_only_text) The default value. Shown on a date option as an ISO-8601–formatted string, or on a text option as a string. - checked_by_default: - type: boolean - description: | - (checkbox) Flag for setting the checkbox to be checked by default. - checkbox_label: - type: string - description: | - (checkbox) Label displayed for the checkbox option. - date_limited: - type: boolean - description: | - (date) Flag to limit the dates allowed to be entered on a date option. - date_limit_mode: - type: string - description: | - (date) The type of limit that is allowed to be entered on a date option. - example: range - enum: - - earliest - - range - - latest - date_earliest_value: - type: string - description: | - (date) The earliest date allowed to be entered on the date option, as an ISO-8601 formatted string. - format: date - date_latest_value: - type: string - description: | - (date) The latest date allowed to be entered on the date option, as an ISO-8601 formatted string. - format: date - file_types_mode: - type: string - description: | - (file) The kind of restriction on the file types that can be uploaded with a file upload option. Values: `specific` - restricts uploads to particular file types; `all` - allows all file types. - example: specific - enum: - - specific - - all - file_types_supported: - type: array - description: | - (file) The type of files allowed to be uploaded if the `file_type_option` is set to `specific`. Values: - `images` - Allows upload of image MIME types (`bmp`, `gif`, `jpg`, `jpeg`, `jpe`, `jif`, `jfif`, `jfi`, `png`, `wbmp`, `xbm`, `tiff`). `documents` - Allows upload of document MIME types (`txt`, `pdf`, `rtf`, `doc`, `docx`, `xls`, `xlsx`, `accdb`, `mdb`, `one`, `pps`, `ppsx`, `ppt`, `pptx`, `pub`, `odt`, `ods`, `odp`, `odg`, `odf`). - `other` - Allows file types defined in the `file_types_other` array. - items: - type: string - example: 'images, documents, other' - file_types_other: - type: array - description: | - (file) A list of other file types allowed with the file upload option. - items: - type: string - example: pdf - file_max_size: - type: integer - description: | - (file) The maximum size for a file that can be used with the file upload option. This will still be limited by the server. - example: 5 - text_characters_limited: - type: boolean - description: | - (text, multi_line_text) Flag to validate the length of a text or multi-line text input. - text_min_length: - type: integer - description: | - (text, multi_line_text) The minimum length allowed for a text or multi-line text option. - example: 1 - text_max_length: - type: integer - description: | - (text, multi_line_text) The maximum length allowed for a text or multi line text option. - example: 55 - text_lines_limited: - type: boolean - description: | - (multi_line_text) Flag to validate the maximum number of lines allowed on a multi-line text input. - example: true - text_max_lines: - type: integer - description: | - (multi_line_text) The maximum number of lines allowed on a multi-line text input. - example: 4 - number_limited: - type: boolean - description: | - (numbers_only_text) Flag to limit the value of a number option. - example: true - number_limit_mode: - type: string - description: | - (numbers_only_text) The type of limit on values entered for a number option. - example: lowest - enum: - - lowest - - highest - - range - number_lowest_value: - type: number - description: | - (numbers_only_text) The lowest allowed value for a number option if `number_limited` is true. - example: 100 - number_highest_value: - type: number - description: | - (numbers_only_text) The highest allowed value for a number option if `number_limited` is true. - number_integers_only: - type: boolean - description: | - (numbers_only_text) Flag to limit the input on a number option to whole numbers only. - example: false - product_list_adjusts_inventory: - type: boolean - description: | - (product_list, product_list_with_images) Flag for automatically adjusting inventory on a product included in the list. - product_list_adjusts_pricing: - type: boolean - description: | - (product_list, product_list_with_images) Flag to add the optional product's price to the main product's price. - product_list_shipping_calc: - type: string - description: | - (product_list, product_list_with_images) How to factor the optional product's weight and package dimensions into the shipping quote. Values: `none` - don't adjust; `weight` - use shipping weight only; `package` - use weight and dimensions. - example: weight - enum: - - none - - weight - - package - description: The values for option config can vary based on the Modifier created. - option_values: - type: array - items: - title: Modifier Value - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the value; increments sequentially. - description: 'Part of Modifier Value Response ' - description: Common Modifier properties. - required: true - responses: - '200': - description: '' - content: - application/json: - schema: - title: Modifier Response - type: object - properties: - data: - title: Modifer - type: object - description: Product Modifier - allOf: - - title: Modifier Base - required: - - required - - type - type: object - properties: - type: - type: string - description: | - BigCommerce API, which determines how it will display on the storefront. Acceptable values: `date`, `checkbox`, `file`, `text`, `multi_line_text`, `numbers_only_text`, `radio_buttons`, `rectangles`, `dropdown`, `product_list`, `product_list_with_images`, `swatch`. Required in a /POST. - enum: - - date - - checkbox - - file - - text - - multi_line_text - - numbers_only_text - - radio_buttons - - rectangles - - dropdown - - product_list - - product_list_with_images - - swatch - x-required: - - post - required: - type: boolean - description: | - Whether or not this modifer is required or not at checkout. Required in a /POST. - x-required: - - post - sort_order: - type: integer - description: The order the modifiers display on the product detail page. - config: - title: Option Config - type: object - properties: - default_value: - type: string - description: | - (date, text, multi_line_text, numbers_only_text) The default value. Shown on a date option as an ISO-8601–formatted string, or on a text option as a string. - checked_by_default: - type: boolean - description: | - (checkbox) Flag for setting the checkbox to be checked by default. - checkbox_label: - type: string - description: | - (checkbox) Label displayed for the checkbox option. - date_limited: - type: boolean - description: | - (date) Flag to limit the dates allowed to be entered on a date option. - date_limit_mode: - type: string - description: | - (date) The type of limit that is allowed to be entered on a date option. - example: range - enum: - - earliest - - range - - latest - date_earliest_value: - type: string - description: | - (date) The earliest date allowed to be entered on the date option, as an ISO-8601 formatted string. - format: date - date_latest_value: - type: string - description: | - (date) The latest date allowed to be entered on the date option, as an ISO-8601 formatted string. - format: date - file_types_mode: - type: string - description: | - (file) The kind of restriction on the file types that can be uploaded with a file upload option. Values: `specific` - restricts uploads to particular file types; `all` - allows all file types. - example: specific - enum: - - specific - - all - file_types_supported: - type: array - description: | - (file) The type of files allowed to be uploaded if the `file_type_option` is set to `specific`. Values: - `images` - Allows upload of image MIME types (`bmp`, `gif`, `jpg`, `jpeg`, `jpe`, `jif`, `jfif`, `jfi`, `png`, `wbmp`, `xbm`, `tiff`). `documents` - Allows upload of document MIME types (`txt`, `pdf`, `rtf`, `doc`, `docx`, `xls`, `xlsx`, `accdb`, `mdb`, `one`, `pps`, `ppsx`, `ppt`, `pptx`, `pub`, `odt`, `ods`, `odp`, `odg`, `odf`). - `other` - Allows file types defined in the `file_types_other` array. - items: - type: string - example: 'images, documents, other' - file_types_other: - type: array - description: | - (file) A list of other file types allowed with the file upload option. - items: - type: string - example: pdf - file_max_size: - type: integer - description: | - (file) The maximum size for a file that can be used with the file upload option. This will still be limited by the server. - example: 5 - text_characters_limited: - type: boolean - description: | - (text, multi_line_text) Flag to validate the length of a text or multi-line text input. - text_min_length: - type: integer - description: | - (text, multi_line_text) The minimum length allowed for a text or multi-line text option. - example: 1 - text_max_length: - type: integer - description: | - (text, multi_line_text) The maximum length allowed for a text or multi line text option. - example: 55 - text_lines_limited: - type: boolean - description: | - (multi_line_text) Flag to validate the maximum number of lines allowed on a multi-line text input. - example: true - text_max_lines: - type: integer - description: | - (multi_line_text) The maximum number of lines allowed on a multi-line text input. - example: 4 - number_limited: - type: boolean - description: | - (numbers_only_text) Flag to limit the value of a number option. - example: true - number_limit_mode: - type: string - description: | - (numbers_only_text) The type of limit on values entered for a number option. - example: lowest - enum: - - lowest - - highest - - range - number_lowest_value: - type: number - description: | - (numbers_only_text) The lowest allowed value for a number option if `number_limited` is true. - example: 100 - number_highest_value: - type: number - description: | - (numbers_only_text) The highest allowed value for a number option if `number_limited` is true. - number_integers_only: - type: boolean - description: | - (numbers_only_text) Flag to limit the input on a number option to whole numbers only. - example: false - product_list_adjusts_inventory: - type: boolean - description: | - (product_list, product_list_with_images) Flag for automatically adjusting inventory on a product included in the list. - product_list_adjusts_pricing: - type: boolean - description: | - (product_list, product_list_with_images) Flag to add the optional product's price to the main product's price. - product_list_shipping_calc: - type: string - description: | - (product_list, product_list_with_images) How to factor the optional product's weight and package dimensions into the shipping quote. Values: `none` - don't adjust; `weight` - use shipping weight only; `package` - use weight and dimensions. - example: weight - enum: - - none - - weight - - package - description: The values for option config can vary based on the Modifier created. - option_values: - type: array - items: - title: Modifier Value - type: object - description: 'Part of Modifier Value Response ' - allOf: - - title: Modifier Value Base - type: object - allOf: - - title: Option Value Base - required: - - label - - sort_order - type: object - properties: - is_default: - type: boolean - description: | - The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. - example: false - label: - type: string - description: | - The text display identifying the value on the storefront. Required in a /POST. - example: Green - x-required: - - post - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the value will be displayed on the product page. Required in a /POST. - example: 0 - x-required: - - post - value_data: - type: object - properties: {} - description: | - Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. - description: Common Option Value properties. - - type: object - properties: - adjusters: - type: object - properties: - price: - title: Adjuster - type: object - properties: - adjuster: - type: string - description: | - The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - enum: - - relative - - percentage - x-nullable: true - adjuster_value: - type: number - description: | - The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. - example: 5 - description: Adjuster for Complex Rules. - weight: - title: Adjuster - type: object - properties: - adjuster: - type: string - description: | - The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - enum: - - relative - - percentage - x-nullable: true - adjuster_value: - type: number - description: | - The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. - example: 5 - description: Adjuster for Complex Rules. - image_url: - type: string - description: | - The URL for an image displayed on the storefront when the modifier value is selected.Limit of 8MB per file. - example: 'https://cdn8.bigcommerce.com/s-{{store_hash}}/products/184/images/445/naturalcanvascart2_1024x1024__92347__29648.1534344533.1280.1280.jpg?c=2' - purchasing_disabled: - type: object - properties: - status: - type: boolean - description: | - Flag for whether the modifier value disables purchasing when selected on the storefront. This can be used for temporarily disabling a particular modifier value. - message: - type: string - description: | - The message displayed on the storefront when the purchasing disabled status is `true`. - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the value; increments sequentially. - description: Common Modifier properties. - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the modifier; increments sequentially. - example: 12 - product_id: - type: integer - description: | - The unique numeric ID of the product to which the option belongs. - example: 77 - name: - type: string - description: | - The unique option name. Auto-generated from the display name, a timestamp, and the product ID. - example: Add-a-$5-Donation1535039590-191 - display_name: - type: string - description: | - The name of the option shown on the storefront. - example: Donation - meta: - $ref: '#/components/schemas/metaEmpty_Full' - '409': - description: | - The `Modifier` was in conflict with another modifier or option. This is the result of duplicate unique fields, such as `name`. - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - '422': - description: | - The `Modifier` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - x-codegen-request-body-name: Modifier - delete: - tags: - - Product Modifiers - summary: Delete a Modifier - description: Deletes a *Product Modifier*. - operationId: deleteModifierById - parameters: - - name: modifier_id - in: path - description: | - The ID of the `Modifier`. - required: true - schema: - type: integer - responses: - '204': - description: '' - content: {} - parameters: - - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/ProductIdParam' - - $ref: '#/components/parameters/ModifierIdParam' - '/catalog/products/{product_id}/modifiers/{modifier_id}/values': - get: - tags: - - Product Modifier Values - summary: Get All Modifier Values - description: Returns a list of all product *Modifier Values*. Optional parameters can be passed in. - operationId: getModifierValues - parameters: - - name: modifier_id - in: path - description: | - The ID of the `Modifier`. - required: true - schema: - type: integer - - - name: include_fields - in: query - description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' - schema: - type: string - - name: exclude_fields - in: query - description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' - schema: - type: string - - name: page - in: query - description: Specifies the page number in a limited (paginated) list of products. - schema: - type: integer - - name: limit - in: query - description: Controls the number of items per page in a limited (paginated) list of products. - schema: - type: integer - responses: - '200': - description: '' - content: - application/json: - schema: - title: Modifier Value Collection Response - type: object - properties: - data: - type: array - items: - $ref: '#/components/schemas/productModifierOptionValue_Full' - meta: - $ref: '#/components/schemas/metaCollection_Full' - description: Returns for GET All Modifier Values on a Product - example: - data: - - id: 190 - option_id: 222 - label: 'Yes' - sort_order: 0 - value_data: - checked_value: true - is_default: false - adjusters: - price: - adjuster: relative - adjuster_value: 5 - weight: {} - image_url: '' - purchasing_disabled: - status: false - message: '' - - id: 191 - option_id: 222 - label: 'No' - sort_order: 1 - value_data: - checked_value: false - is_default: true - adjusters: - price: {} - weight: {} - image_url: '' - purchasing_disabled: - status: false - message: '' - meta: - pagination: - total: 2 - count: 2 - per_page: 50 - current_page: 1 - total_pages: 1 - links: - current: '?page=1&limit=50' - post: - tags: - - Product Modifier Values - summary: Create Modifier Value - description: |- - Creates a *Modifier Value*. - - **Required Fields** - * label - * sort_order - - **Read-Only Fields** - * id - operationId: createModifierValue - parameters: - - $ref: '#/components/parameters/ContentType' - - name: modifier_id - in: path - description: | - The ID of the `Modifier`. - required: true - schema: - type: integer - requestBody: - content: - application/json: - schema: - title: Modifier Value Post - description: The model for a POST to create a modifier value on a product. - allOf: - - title: Modifier Value Base - allOf: - - title: Option Value Base - required: - - label - - sort_order - type: object - properties: - is_default: - type: boolean - description: | - The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. - example: false - label: - type: string - description: | - The text display identifying the value on the storefront. Required in a /POST. - example: Green - x-required: - - post - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the value will be displayed on the product page. Required in a /POST. - example: 0 - x-required: - - post - value_data: - type: object - properties: {} - description: | - Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. - description: Common Option Value properties. - - type: object - properties: - adjusters: - type: object - properties: - price: - title: Adjuster - type: object - properties: - adjuster: - type: string - description: | - The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - nullable: true - enum: - - relative - - percentage - adjuster_value: - type: number - description: | - The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. - example: 5 - description: Adjuster for Complex Rules. - weight: - title: Adjuster - type: object - properties: - adjuster: - type: string - description: | - The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - nullable: true - enum: - - relative - - percentage - adjuster_value: - type: number - description: | - The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. - example: 5 - description: Adjuster for Complex Rules. - image_url: - type: string - description: | - The URL for an image displayed on the storefront when the modifier value is selected.Limit of 8MB per file. - example: 'https://cdn8.bigcommerce.com/s-{{store_hash}}/products/184/images/445/naturalcanvascart2_1024x1024__92347__29648.1534344533.1280.1280.jpg?c=2' - purchasing_disabled: - type: object - properties: - status: - type: boolean - description: | - Flag for whether the modifier value disables purchasing when selected on the storefront. This can be used for temporarily disabling a particular modifier value. - message: - type: string - description: | - The message displayed on the storefront when the purchasing disabled status is `true`. - required: true - responses: - '200': - description: '' - content: - application/json: - schema: - title: Modifier Value Response - type: object - properties: - data: - title: Modifier Value - type: object - description: 'Part of Modifier Value Response ' - allOf: - - title: Modifier Value Base - type: object - allOf: - - title: Option Value Base - required: - - label - - sort_order - type: object - properties: - is_default: - type: boolean - description: | - The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. - example: false - label: - type: string - description: | - The text display identifying the value on the storefront. Required in a /POST. - example: Green - x-required: - - post - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the value will be displayed on the product page. Required in a /POST. - example: 0 - x-required: - - post - value_data: - type: object - properties: {} - description: | - Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. - description: Common Option Value properties. - - type: object - properties: - adjusters: - type: object - properties: - price: - title: Adjuster - type: object - properties: - adjuster: - type: string - description: | - The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - enum: - - relative - - percentage - x-nullable: true - adjuster_value: - type: number - description: | - The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. - example: 5 - description: Adjuster for Complex Rules. - weight: - title: Adjuster - type: object - properties: - adjuster: - type: string - description: | - The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - enum: - - relative - - percentage - x-nullable: true - adjuster_value: - type: number - description: | - The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. - example: 5 - description: Adjuster for Complex Rules. - image_url: - type: string - description: | - The URL for an image displayed on the storefront when the modifier value is selected.Limit of 8MB per file. - example: 'https://cdn8.bigcommerce.com/s-{{store_hash}}/products/184/images/445/naturalcanvascart2_1024x1024__92347__29648.1534344533.1280.1280.jpg?c=2' - purchasing_disabled: - type: object - properties: - status: - type: boolean - description: | - Flag for whether the modifier value disables purchasing when selected on the storefront. This can be used for temporarily disabling a particular modifier value. - message: - type: string - description: | - The message displayed on the storefront when the purchasing disabled status is `true`. - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the value; increments sequentially. - meta: - $ref: '#/components/schemas/metaEmpty_Full' - example: - data: - id: 190 - option_id: 222 - label: 'Yes' - sort_order: 0 - value_data: {} - is_default: false - adjusters: - price: - adjuster: relative - adjuster_value: 5 - weight: {} - image_url: '' - purchasing_disabled: - status: false - message: '' - meta: {} - '422': - description: | - The `ModifierValue` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - x-codegen-request-body-name: ModifierValue - parameters: - - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/ProductIdParam' - - $ref: '#/components/parameters/ModifierIdParam' - '/catalog/products/{product_id}/modifiers/{modifier_id}/values/{value_id}': - get: - tags: - - Product Modifier Values - summary: Get a Modifier Value - description: Returns a single *Modifier Value*. Optional parameters can be passed in. - operationId: getModifierValueById - parameters: - - name: modifier_id - in: path - description: | - The ID of the `Modifier`. - required: true - schema: - type: integer - - name: value_id - in: path - description: | - The ID of the `Modifier/Option Value`. - required: true - schema: - type: integer - - - name: include_fields - in: query - description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' - schema: - type: string - - name: exclude_fields - in: query - description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' - schema: - type: string - responses: - '200': - description: '' - content: - application/json: - schema: - title: Modifier Value Response - type: object - properties: - data: - $ref: '#/components/schemas/productModifierOptionValue_Full' - meta: - $ref: '#/components/schemas/metaEmpty_Full' - example: - data: - id: 190 - option_id: 222 - label: 'Yes' - sort_order: 0 - value_data: {} - is_default: false - adjusters: - price: - adjuster: relative - adjuster_value: 5 - weight: {} - image_url: '' - purchasing_disabled: - status: false - message: '' - meta: {} - '404': - description: | - The resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - security: - - X-Auth-Token: [] - put: - tags: - - Product Modifier Values - summary: Update a Modifier Value - description: |- - Updates a *Modifier Value*. - - **Required Fields** - * none - - **Read-Only Fields** - * id - operationId: updateModifierValue - parameters: - - $ref: '#/components/parameters/ContentType' - - name: modifier_id - in: path - description: | - The ID of the `Modifier`. - required: true - schema: - type: integer - - name: value_id - in: path - description: | - The ID of the `Modifier/Option Value`. - required: true - schema: - type: integer - requestBody: - content: - application/json: - schema: - title: Modifier Value Put - description: The model for a PUT to update a modifier value on a product. - allOf: - - title: Modifier Value Base - allOf: - - title: Option Value Base - required: - - label - - sort_order - type: object - properties: - is_default: - type: boolean - description: | - The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. - example: false - label: - type: string - description: | - The text display identifying the value on the storefront. Required in a /POST. - example: Green - x-required: - - post - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the value will be displayed on the product page. Required in a /POST. - example: 0 - x-required: - - post - value_data: - type: object - properties: {} - description: | - Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. - description: Common Option Value properties. - - type: object - properties: - adjusters: - type: object - properties: - price: - title: Adjuster - type: object - properties: - adjuster: - type: string - description: | - The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - nullable: true - enum: - - relative - - percentage - adjuster_value: - type: number - description: | - The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. - example: 5 - description: Adjuster for Complex Rules. - weight: - title: Adjuster - type: object - properties: - adjuster: - type: string - description: | - The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - nullable: true - enum: - - relative - - percentage - adjuster_value: - type: number - description: | - The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. - example: 5 - description: Adjuster for Complex Rules. - image_url: - type: string - description: | - The URL for an image displayed on the storefront when the modifier value is selected.Limit of 8MB per file. - example: 'https://cdn8.bigcommerce.com/s-{{store_hash}}/products/184/images/445/naturalcanvascart2_1024x1024__92347__29648.1534344533.1280.1280.jpg?c=2' - purchasing_disabled: - type: object - properties: - status: - type: boolean - description: | - Flag for whether the modifier value disables purchasing when selected on the storefront. This can be used for temporarily disabling a particular modifier value. - message: - type: string - description: | - The message displayed on the storefront when the purchasing disabled status is `true`. - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the value; increments sequentially. - x-required: - - put - required: true - responses: - '200': - description: '' - content: - application/json: - schema: - title: Modifier Value Response - type: object - properties: - data: - title: Modifier Value - type: object - description: 'Part of Modifier Value Response ' - allOf: - - title: Modifier Value Base - type: object - allOf: - - title: Option Value Base - required: - - label - - sort_order - type: object - properties: - is_default: - type: boolean - description: | - The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. - example: false - label: - type: string - description: | - The text display identifying the value on the storefront. Required in a /POST. - example: Green - x-required: - - post - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the value will be displayed on the product page. Required in a /POST. - example: 0 - x-required: - - post - value_data: - type: object - properties: {} - description: | - Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. - description: Common Option Value properties. - - type: object - properties: - adjusters: - type: object - properties: - price: - title: Adjuster - type: object - properties: - adjuster: - type: string - description: | - The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - enum: - - relative - - percentage - x-nullable: true - adjuster_value: - type: number - description: | - The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. - example: 5 - description: Adjuster for Complex Rules. - weight: - title: Adjuster - type: object - properties: - adjuster: - type: string - description: | - The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - enum: - - relative - - percentage - x-nullable: true - adjuster_value: - type: number - description: | - The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. - example: 5 - description: Adjuster for Complex Rules. - image_url: - type: string - description: | - The URL for an image displayed on the storefront when the modifier value is selected.Limit of 8MB per file. - example: 'https://cdn8.bigcommerce.com/s-{{store_hash}}/products/184/images/445/naturalcanvascart2_1024x1024__92347__29648.1534344533.1280.1280.jpg?c=2' - purchasing_disabled: - type: object - properties: - status: - type: boolean - description: | - Flag for whether the modifier value disables purchasing when selected on the storefront. This can be used for temporarily disabling a particular modifier value. - message: - type: string - description: | - The message displayed on the storefront when the purchasing disabled status is `true`. - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the value; increments sequentially. - meta: - $ref: '#/components/schemas/metaEmpty_Full' - example: - data: - id: 190 - option_id: 222 - label: 'Yes' - sort_order: 0 - value_data: {} - is_default: false - adjusters: - price: - adjuster: relative - adjuster_value: 5 - weight: {} - image_url: '' - purchasing_disabled: - status: false - message: '' - meta: {} - '422': - description: | - The `ModifierValue` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - x-codegen-request-body-name: ModifierValue - delete: - tags: - - Product Modifier Values - summary: Delete Modifier Value - description: Deletes a *Modifier Value*. - operationId: deleteModifierValueById - parameters: - - name: modifier_id - in: path - description: | - The ID of the `Modifier`. - required: true - schema: - type: integer - - name: value_id - in: path - description: | - The ID of the `Modifier/Option Value`. - required: true - schema: - type: integer - responses: - '204': - description: '' - content: {} - parameters: - - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/ProductIdParam' - - $ref: '#/components/parameters/ModifierIdParam' - - $ref: '#/components/parameters/ValueIdParam' - '/catalog/products/{product_id}/modifiers/{modifier_id}/values/{value_id}/image': - post: - tags: - - Product Modifier Images - summary: Create Modifier Image - description: |- - Creates a *Modifier Image*. - - The image will show on the storefront when the value is selected. - - **Required Fields** - - image_file: Form posts are the only accepted upload option. - operationId: createModifierImage - parameters: - - $ref: '#/components/parameters/ContentType' - - name: modifier_id - in: path - description: | - The ID of the `Modifier`. - required: true - schema: - type: integer - - name: value_id - in: path - description: | - The ID of the `Modifier`. - required: true - schema: - type: integer - requestBody: - content: - multipart/form-data: - schema: - type: object - properties: - image_file: - type: string - format: binary - responses: - '200': - description: '' - content: - application/json: - schema: - title: Image Response - type: object - properties: - data: - title: Resource Image - type: object - properties: - image_url: - type: string - description: | - A public URL for a GIF, JPEG, or PNG image. Limit of 8MB per file. - description: 'An object containing a publicly accessible image URL, or a form post that contains an image file.' - meta: - $ref: '#/components/schemas/metaEmpty_Full' - description: |- - Image Response returns for: - * Create Variant Image - * Create Modifier Image - * Create Category Image - * Create Brand Image - example: - data: - image_url: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/product_images/attribute_rule_images/85_source_1536863430.png' - meta: {} - '400': - description: Bad Request. The requested resource could not be downloaded and may be invalid. Possible reasons include malformed request syntax or the file host blocking requests. - content: - application/json: - schema: - type: object - properties: {} - '404': - description: | - The resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - '422': - description: | - Modifier image was not valid. This is the result of missing `image_file` fields, or of a non-URL value for the `image_file` field. See the response for more details. - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - parameters: - - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/ProductIdParam' - - $ref: '#/components/parameters/ModifierIdParam' - - $ref: '#/components/parameters/ValueIdParam' - '/catalog/products/{product_id}/complex-rules': - get: - tags: - - Product Complex Rules - summary: Get Complex Rules - description: Returns a list of all product *Complex Rules*. Optional parameters may be passed in. - operationId: getComplexRules - parameters: - - name: include_fields - in: query - description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' - schema: - type: string - - name: exclude_fields - in: query - description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' - schema: - type: string - - name: page - in: query - description: Specifies the page number in a limited (paginated) list of products. - schema: - type: integer - - name: limit - in: query - description: Controls the number of items per page in a limited (paginated) list of products. - schema: - type: integer - responses: - '200': - description: '' - content: - application/json: - schema: - title: Complex Rule Collection Response - type: object - properties: - data: - type: array - items: - $ref: '#/components/schemas/complexRule_Base' - meta: - $ref: '#/components/schemas/metaCollection_Full' - description: Complex Rule Response - example: - data: - - id: 82 - product_id: 195 - sort_order: 0 - enabled: true - stop: false - price_adjuster: - adjuster: relative - adjuster_value: 8 - weight_adjuster: {} - purchasing_disabled: false - purchasing_disabled_message: '' - purchasing_hidden: false - image_url: '' - conditions: - - rule_id: 82 - modifier_id: 221 - modifier_value_id: 175 - variant_id: 1 - combination_id: 0 - - id: 83 - product_id: 195 - sort_order: 1 - enabled: true - stop: false - price_adjuster: {} - weight_adjuster: - adjuster: relative - adjuster_value: 3 - purchasing_disabled: false - purchasing_disabled_message: '' - purchasing_hidden: false - image_url: '' - conditions: - - rule_id: 83 - modifier_id: 221 - modifier_value_id: 174 - variant_id: 1 - combination_id: 0 - meta: - pagination: - total: 2 - count: 2 - per_page: 50 - current_page: 1 - total_pages: 1 - links: - current: '?page=1&limit=50' - post: - tags: - - Product Complex Rules - summary: Create a Complex Rule - description: |- - Creates a product *Complex Rule*. - - **Required Fields** - - modifier_id - - modifier_value_id - - modifier_value_id - - variant_id - - **Read-Only Fields** - - complex_rule_id - - conditions_id - - rule_id - - combination_id - - id - operationId: createComplexRule - parameters: - - $ref: '#/components/parameters/ContentType' - requestBody: - content: - application/json: - schema: - title: Complex Rule - type: object - properties: - product_id: - type: integer - description: | - The unique numeric ID of the product with which the rule is associated; increments sequentially. - nullable: true - example: 67 - x-required: - - post - - put - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The priority to give this rule when making adjustments to the product properties. - example: 0 - enabled: - type: boolean - description: | - Flag for determining whether the rule is to be used when adjusting a product's price, weight, image, or availabilty. - example: true - stop: - type: boolean - description: | - Flag for determining whether other rules should not be applied after this rule has been applied. - purchasing_disabled: - type: boolean - description: | - Flag for determining whether the rule should disable purchasing of a product when the conditions are applied. - purchasing_disabled_message: - maxLength: 255 - minLength: 0 - type: string - description: | - Message displayed on the storefront when a rule disables the purchasing of a product. - example: This product is not available at this time. - purchasing_hidden: - type: boolean - description: | - Flag for determining whether the rule should hide purchasing of a product when the conditions are applied. - image_url: - type: string - description: | - The URL for an image displayed on the storefront when the conditions are applied. Limit of 8MB per file. - example: 'https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png' - price_adjuster: - title: Adjuster - type: object - properties: - adjuster: - type: string - description: | - The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - nullable: true - enum: - - relative - - percentage - adjuster_value: - type: number - description: | - The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. - example: 5 - description: Adjuster for Complex Rules. - weight_adjuster: - title: Adjuster - type: object - properties: - adjuster: - type: string - description: | - The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - nullable: true - enum: - - relative - - percentage - adjuster_value: - type: number - description: | - The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. - example: 5 - description: Adjuster for Complex Rules. - conditions: - type: array - items: - title: Complex Rule Condition - required: - - modifier_id - - modifier_value_id - - variant_id - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the rule condition; increments sequentially. Read-Only - nullable: true - example: 3 - rule_id: - type: integer - description: |- - The unique numeric ID of the rule with which the condition is associated. - Read-Only - nullable: true - example: 4 - modifier_id: - type: integer - description: |- - The unique numeric ID of the modifier with which the rule condition is associated. - Required in /POST. - nullable: true - example: 55 - modifier_value_id: - type: integer - description: |- - The unique numeric ID of the modifier value with which the rule condition is associated. - Required in /POST. - nullable: true - example: 256 - variant_id: - type: integer - description: |- - The unique numeric ID of the variant with which the rule condition is associated. - Required in /POST. - nullable: true - example: 1 - combination_id: - type: integer - description: | - (READ-ONLY:) The unique numeric ID of the SKU (v2 API), or Combination, with which the rule condition is associated. This is to maintain cross-compatibility between v2 and v3. - description: 'Complex rules may return with conditions that apply to one or more variants, or with a single modifier value (if the rules were created using the v2 API or the control panel). Complex rules created or updated in the v3 API must have conditions that either reference multiple `modifier_value_id`’s, or else reference a `modifier_value_id` and a `variant_id`.' - description: Common ComplexRule properties. - required: true - responses: - '200': - description: '' - content: - application/json: - schema: - type: object - properties: - data: - title: Complex Rule - type: object - properties: - id: - type: integer - description: |- - The unique numeric ID of the rule; increments sequentially. - Read-Only - example: 5 - product_id: - type: integer - description: | - The unique numeric ID of the product with which the rule is associated; increments sequentially. - nullable: true - example: 67 - x-required: - - post - - put - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The priority to give this rule when making adjustments to the product properties. - example: 0 - enabled: - type: boolean - description: | - Flag for determining whether the rule is to be used when adjusting a product's price, weight, image, or availabilty. - example: true - stop: - type: boolean - description: | - Flag for determining whether other rules should not be applied after this rule has been applied. - purchasing_disabled: - type: boolean - description: | - Flag for determining whether the rule should disable purchasing of a product when the conditions are applied. - purchasing_disabled_message: - maxLength: 255 - minLength: 0 - type: string - description: | - Message displayed on the storefront when a rule disables the purchasing of a product. - example: This product is not available at this time. - purchasing_hidden: - type: boolean - description: | - Flag for determining whether the rule should hide purchasing of a product when the conditions are applied. - image_url: - type: string - description: | - The URL for an image displayed on the storefront when the conditions are applied. Limit of 8MB per file. - example: 'https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png' - price_adjuster: - title: Adjuster - type: object - properties: - adjuster: - type: string - description: | - The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - nullable: true - enum: - - relative - - percentage - adjuster_value: - type: number - description: | - The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. - example: 5 - description: Adjuster for Complex Rules. - weight_adjuster: - title: Adjuster - type: object - properties: - adjuster: - type: string - description: | - The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - nullable: true - enum: - - relative - - percentage - adjuster_value: - type: number - description: | - The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. - example: 5 - description: Adjuster for Complex Rules. - conditions: - type: array - items: - title: Complex Rule Condition - required: - - modifier_id - - modifier_value_id - - variant_id - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the rule condition; increments sequentially. Read-Only - nullable: true - example: 3 - rule_id: - type: integer - description: |- - The unique numeric ID of the rule with which the condition is associated. - Read-Only - nullable: true - example: 4 - modifier_id: - type: integer - description: |- - The unique numeric ID of the modifier with which the rule condition is associated. - Required in /POST. - nullable: true - example: 55 - modifier_value_id: - type: integer - description: |- - The unique numeric ID of the modifier value with which the rule condition is associated. - Required in /POST. - nullable: true - example: 256 - variant_id: - type: integer - description: |- - The unique numeric ID of the variant with which the rule condition is associated. - Required in /POST. - nullable: true - example: 1 - combination_id: - type: integer - description: | - (READ-ONLY:) The unique numeric ID of the SKU (v2 API), or Combination, with which the rule condition is associated. This is to maintain cross-compatibility between v2 and v3. - description: 'Complex rules may return with conditions that apply to one or more variants, or with a single modifier value (if the rules were created using the v2 API or the control panel). Complex rules created or updated in the v3 API must have conditions that either reference multiple `modifier_value_id`’s, or else reference a `modifier_value_id` and a `variant_id`.' - description: Common ComplexRule properties. - meta: - $ref: '#/components/schemas/metaEmpty_Full' - '409': - description: | - The `ComplexRule` was in conflict with another `ComplexRule`. This is the result of duplicate conditions. - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - '422': - description: | - The `ComplexRule` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - x-codegen-request-body-name: ComplexRule - parameters: - - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/ProductIdParam' - '/catalog/products/{product_id}/complex-rules/{complex_rule_id}': - get: - tags: - - Product Complex Rules - summary: Get a Complex Rule - description: Returns a single *Complex Rule*. Optional parameters can be passed in. - operationId: getComplexRuleById - parameters: - - name: complex_rule_id - in: path - description: | - The ID of the `ComplexRule`. - required: true - schema: - type: integer - - - name: include_fields - in: query - description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' - schema: - type: string - - name: exclude_fields - in: query - description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' - schema: - type: string - responses: - '200': - description: '' - content: - application/json: - schema: - type: object - properties: - data: - title: Complex Rule - type: object - properties: - id: - type: integer - description: |- - The unique numeric ID of the rule; increments sequentially. - Read-Only - example: 5 - product_id: - type: integer - description: | - The unique numeric ID of the product with which the rule is associated; increments sequentially. - example: 67 - x-required: - - post - - put - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The priority to give this rule when making adjustments to the product properties. - example: 0 - enabled: - type: boolean - description: | - Flag for determining whether the rule is to be used when adjusting a product's price, weight, image, or availabilty. - example: true - stop: - type: boolean - description: | - Flag for determining whether other rules should not be applied after this rule has been applied. - purchasing_disabled: - type: boolean - description: | - Flag for determining whether the rule should disable purchasing of a product when the conditions are applied. - purchasing_disabled_message: - maxLength: 255 - minLength: 0 - type: string - description: | - Message displayed on the storefront when a rule disables the purchasing of a product. - example: This product is not available at this time. - purchasing_hidden: - type: boolean - description: | - Flag for determining whether the rule should hide purchasing of a product when the conditions are applied. - image_url: - type: string - description: | - The URL for an image displayed on the storefront when the conditions are applied. Limit of 8MB per file. - example: 'https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png' - price_adjuster: - title: Adjuster - type: object - properties: - adjuster: - type: string - description: | - The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - enum: - - relative - - percentage - adjuster_value: - type: number - description: | - The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. - example: 5 - description: Adjuster for Complex Rules. - weight_adjuster: - title: Adjuster - type: object - properties: - adjuster: - type: string - description: | - The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - enum: - - relative - - percentage - adjuster_value: - type: number - description: | - The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. - example: 5 - description: Adjuster for Complex Rules. - conditions: - type: array - items: - title: Complex Rule Condition - required: - - modifier_id - - modifier_value_id - - variant_id - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the rule condition; increments sequentially. Read-Only - example: 3 - rule_id: - type: integer - description: |- - The unique numeric ID of the rule with which the condition is associated. - Read-Only - example: 4 - modifier_id: - type: integer - description: |- - The unique numeric ID of the modifier with which the rule condition is associated. - Required in /POST. - example: 55 - modifier_value_id: - type: integer - description: |- - The unique numeric ID of the modifier value with which the rule condition is associated. - Required in /POST. - example: 256 - variant_id: - type: integer - description: |- - The unique numeric ID of the variant with which the rule condition is associated. - Required in /POST. - example: 1 - combination_id: - type: integer - description: | - (READ-ONLY:) The unique numeric ID of the SKU (v2 API), or Combination, with which the rule condition is associated. This is to maintain cross-compatibility between v2 and v3. - description: 'Complex rules may return with conditions that apply to one or more variants, or with a single modifier value (if the rules were created using the v2 API or the control panel). Complex rules created or updated in the v3 API must have conditions that either reference multiple `modifier_value_id`’s, or else reference a `modifier_value_id` and a `variant_id`.' - description: Common ComplexRule properties. - meta: - $ref: '#/components/schemas/metaEmpty_Full' - '404': - description: | - The resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - put: - tags: - - Product Complex Rules - summary: Update a Complex Rule - description: |- - Updates a *Complex Rule*. - - **Required Fields**: - - none - - **Read-Only Fields**: - - complex_rule_id - - conditions_id - - rule_id - - combination_id - - id - operationId: updateComplexRule - parameters: - - $ref: '#/components/parameters/ContentType' - - name: complex_rule_id - in: path - description: | - The ID of the `ComplexRule`. - required: true - schema: - type: integer - - requestBody: - content: - application/json: - schema: - title: Complex Rule - type: object - properties: - id: - type: integer - description: |- - The unique numeric ID of the rule; increments sequentially. - Read-Only - example: 5 - product_id: - type: integer - description: | - The unique numeric ID of the product with which the rule is associated; increments sequentially. - nullable: true - example: 67 - x-required: - - post - - put - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The priority to give this rule when making adjustments to the product properties. - example: 0 - enabled: - type: boolean - description: | - Flag for determining whether the rule is to be used when adjusting a product's price, weight, image, or availabilty. - example: true - stop: - type: boolean - description: | - Flag for determining whether other rules should not be applied after this rule has been applied. - purchasing_disabled: - type: boolean - description: | - Flag for determining whether the rule should disable purchasing of a product when the conditions are applied. - purchasing_disabled_message: - maxLength: 255 - minLength: 0 - type: string - description: | - Message displayed on the storefront when a rule disables the purchasing of a product. - example: This product is not available at this time. - purchasing_hidden: - type: boolean - description: | - Flag for determining whether the rule should hide purchasing of a product when the conditions are applied. - image_url: - type: string - description: | - The URL for an image displayed on the storefront when the conditions are applied. Limit of 8MB per file. - example: 'https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png' - price_adjuster: - title: Adjuster - type: object - properties: - adjuster: - type: string - description: | - The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - nullable: true - enum: - - relative - - percentage - adjuster_value: - type: number - description: | - The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. - example: 5 - description: Adjuster for Complex Rules. - weight_adjuster: - title: Adjuster - type: object - properties: - adjuster: - type: string - description: | - The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - nullable: true - enum: - - relative - - percentage - adjuster_value: - type: number - description: | - The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. - example: 5 - description: Adjuster for Complex Rules. - conditions: - type: array - items: - title: Complex Rule Condition - required: - - modifier_id - - modifier_value_id - - variant_id - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the rule condition; increments sequentially. Read-Only - nullable: true - example: 3 - rule_id: - type: integer - description: |- - The unique numeric ID of the rule with which the condition is associated. - Read-Only - nullable: true - example: 4 - modifier_id: - type: integer - description: |- - The unique numeric ID of the modifier with which the rule condition is associated. - Required in /POST. - nullable: true - example: 55 - modifier_value_id: - type: integer - description: |- - The unique numeric ID of the modifier value with which the rule condition is associated. - Required in /POST. - nullable: true - example: 256 - variant_id: - type: integer - description: |- - The unique numeric ID of the variant with which the rule condition is associated. - Required in /POST. - nullable: true - example: 1 - combination_id: - type: integer - description: | - (READ-ONLY:) The unique numeric ID of the SKU (v2 API), or Combination, with which the rule condition is associated. This is to maintain cross-compatibility between v2 and v3. - description: 'Complex rules may return with conditions that apply to one or more variants, or with a single modifier value (if the rules were created using the v2 API or the control panel). Complex rules created or updated in the v3 API must have conditions that either reference multiple `modifier_value_id`’s, or else reference a `modifier_value_id` and a `variant_id`.' - description: Common ComplexRule properties. - required: true - responses: - '200': - description: '' - content: - application/json: - schema: - type: object - properties: - data: - title: Complex Rule - type: object - properties: - id: - type: integer - description: |- - The unique numeric ID of the rule; increments sequentially. - Read-Only - example: 5 - product_id: - type: integer - description: | - The unique numeric ID of the product with which the rule is associated; increments sequentially. - example: 67 - x-required: - - post - - put - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The priority to give this rule when making adjustments to the product properties. - example: 0 - enabled: - type: boolean - description: | - Flag for determining whether the rule is to be used when adjusting a product's price, weight, image, or availabilty. - example: true - stop: - type: boolean - description: | - Flag for determining whether other rules should not be applied after this rule has been applied. - purchasing_disabled: - type: boolean - description: | - Flag for determining whether the rule should disable purchasing of a product when the conditions are applied. - purchasing_disabled_message: - maxLength: 255 - minLength: 0 - type: string - description: | - Message displayed on the storefront when a rule disables the purchasing of a product. - example: This product is not available at this time. - purchasing_hidden: - type: boolean - description: | - Flag for determining whether the rule should hide purchasing of a product when the conditions are applied. - image_url: - type: string - description: | - The URL for an image displayed on the storefront when the conditions are applied. Limit of 8MB per file. - example: 'https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png' - price_adjuster: - title: Adjuster - type: object - properties: - adjuster: - type: string - description: | - The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - enum: - - relative - - percentage - adjuster_value: - type: number - description: | - The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. - example: 5 - description: Adjuster for Complex Rules. - weight_adjuster: - title: Adjuster - type: object - properties: - adjuster: - type: string - description: | - The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - enum: - - relative - - percentage - adjuster_value: - type: number - description: | - The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. - example: 5 - description: Adjuster for Complex Rules. - conditions: - type: array - items: - title: Complex Rule Condition - required: - - modifier_id - - modifier_value_id - - variant_id - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the rule condition; increments sequentially. Read-Only - example: 3 - rule_id: - type: integer - description: |- - The unique numeric ID of the rule with which the condition is associated. - Read-Only - example: 4 - modifier_id: - type: integer - description: |- - The unique numeric ID of the modifier with which the rule condition is associated. - Required in /POST. - example: 55 - modifier_value_id: - type: integer - description: |- - The unique numeric ID of the modifier value with which the rule condition is associated. - Required in /POST. - example: 256 - variant_id: - type: integer - description: |- - The unique numeric ID of the variant with which the rule condition is associated. - Required in /POST. - example: 1 - combination_id: - type: integer - description: | - (READ-ONLY:) The unique numeric ID of the SKU (v2 API), or Combination, with which the rule condition is associated. This is to maintain cross-compatibility between v2 and v3. - description: 'Complex rules may return with conditions that apply to one or more variants, or with a single modifier value (if the rules were created using the v2 API or the control panel). Complex rules created or updated in the v3 API must have conditions that either reference multiple `modifier_value_id`’s, or else reference a `modifier_value_id` and a `variant_id`.' - description: Common ComplexRule properties. - meta: - $ref: '#/components/schemas/metaEmpty_Full' - '409': - description: | - The `ComplexRule` was in conflict with another `ComplexRule`. This is the result of duplicate conditions. - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - '422': - description: | - The `ComplexRule` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - x-codegen-request-body-name: ComplexRule - delete: - tags: - - Product Complex Rules - summary: Delete a Complex Rule - description: Deletes a product *Complex Rule*. - operationId: deleteComplexRuleById - parameters: - - name: complex_rule_id - in: path - description: | - The ID of the `ComplexRule`. - required: true - schema: - type: integer - responses: - '204': - description: '' - content: {} - parameters: - - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/ProductIdParam' - - $ref: '#/components/parameters/ComplexRuleIdParam' - '/catalog/products/{product_id}/custom-fields': - get: - tags: - - Product Custom Fields - summary: Get Custom Fields - description: Returns a list of product *Custom Fields*. Optional parameters can be passed in. - operationId: getCustomFields - parameters: - - name: include_fields - in: query - description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' - schema: - type: string - - name: exclude_fields - in: query - description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' - schema: - type: string - - name: page - in: query - description: Specifies the page number in a limited (paginated) list of products. - schema: - type: integer - - name: limit - in: query - description: Controls the number of items per page in a limited (paginated) list of products. - schema: - type: integer - responses: - '200': - description: '' - content: - application/json: - schema: - type: object - properties: - data: - type: array - items: - title: Custom Field - required: - - name - - value - type: object - properties: - id: - minimum: 1 - type: integer - description: |- - The unique numeric ID of the custom field; increments sequentially. - Read-Only - example: 6 - name: - maxLength: 250 - minLength: 1 - type: string - description: | - The name of the field, shown on the storefront, orders, etc. Required for /POST - example: ISBN - x-required: - - post - value: - maxLength: 250 - minLength: 1 - type: string - description: | - The name of the field, shown on the storefront, orders, etc. Required for /POST - example: '1234567890123' - x-required: - - post - description: 'Gets custom fields associated with a product. These allow you to specify additional information that will appear on the product’s page, such as a book’s ISBN or a DVD’s release date.' - meta: - $ref: '#/components/schemas/metaCollection_Full' - example: - data: - - name: Release year - value: '1987' - id: 1 - meta: - pagination: - total: 1 - count: 1 - per_page: 50 - current_page: 1 - total_pages: 1 - links: - previous: '?page=1&limit=50' - current: '?page=1&limit=50' - next: '?page=1&limit=50' - post: - tags: - - Product Custom Fields - summary: Create a Custom Fields - description: |- - Creates a *Custom Field*. - - **Required Fields:** - - name - - value - - **Read-Only:** - - id - - **Limits** - - 200 custom fields per product limit. - - 255 characters per custom field limit. - operationId: createCustomField - parameters: - - $ref: '#/components/parameters/ContentType' - requestBody: - content: - application/json: - schema: - title: Custom Field - required: - - name - - value - type: object - properties: - name: - maxLength: 250 - minLength: 1 - type: string - description: | - The name of the field, shown on the storefront, orders, etc. Required for /POST - example: ISBN - x-required: - - post - value: - maxLength: 250 - minLength: 1 - type: string - description: | - The name of the field, shown on the storefront, orders, etc. Required for /POST - example: '1234567890123' - x-required: - - post - description: 'Gets custom fields associated with a product. These allow you to specify additional information that will appear on the product’s page, such as a book’s ISBN or a DVD’s release date.' - required: true - responses: - '200': - description: '' - content: - application/json: - schema: - type: object - properties: - data: - title: Custom Field - required: - - name - - value - type: object - properties: - id: - minimum: 1 - type: integer - description: |- - The unique numeric ID of the custom field; increments sequentially. - Read-Only - example: 6 - name: - maxLength: 250 - minLength: 1 - type: string - description: | - The name of the field, shown on the storefront, orders, etc. Required for /POST - example: ISBN - x-required: - - post - value: - maxLength: 250 - minLength: 1 - type: string - description: | - The name of the field, shown on the storefront, orders, etc. Required for /POST - example: '1234567890123' - x-required: - - post - description: 'Gets custom fields associated with a product. These allow you to specify additional information that will appear on the product’s page, such as a book’s ISBN or a DVD’s release date.' - meta: - $ref: '#/components/schemas/metaEmpty_Full' - example: - data: - name: Release Year - value: '1976' - id: 2 - meta: {} - '404': - description: | - The parent resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - '422': - description: | - The `CustomField` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - x-codegen-request-body-name: CustomField - parameters: - - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/ProductIdParam' - '/catalog/products/{product_id}/custom-fields/{custom_field_id}': - get: - tags: - - Product Custom Fields - summary: Get a Custom Field - description: Returns a single *Custom Field*. Optional parameters can be passed in. - operationId: getCustomFieldById - parameters: - - name: custom_field_id - in: path - description: | - The ID of the `CustomField`. - required: true - schema: - type: integer - - - name: include_fields - in: query - description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' - schema: - type: string - - name: exclude_fields - in: query - description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' - schema: - type: string - responses: - '200': - description: '' - content: - application/json: - schema: - type: object - properties: - data: - $ref: '#/components/schemas/productCustomField_Base' - meta: - $ref: '#/components/schemas/metaEmpty_Full' - example: - data: - name: Release Year - value: '1976' - id: 2 - meta: {} - '404': - description: | - The resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - put: - tags: - - Product Custom Fields - summary: Update a Custom Field - description: |- - Updates a *Custom Field*. - - **Required Fields** - - none - - **Read-Only** - - id - operationId: updateCustomField - parameters: - - $ref: '#/components/parameters/ContentType' - - name: custom_field_id - in: path - description: | - The ID of the `CustomField`. - required: true - schema: - type: integer - requestBody: - content: - application/json: - schema: - title: Custom Field - required: - - name - - value - type: object - properties: - id: - minimum: 1 - type: integer - description: |- - The unique numeric ID of the custom field; increments sequentially. - Read-Only - example: 6 - name: - maxLength: 250 - minLength: 1 - type: string - description: | - The name of the field, shown on the storefront, orders, etc. Required for /POST - example: ISBN - x-required: - - post - value: - maxLength: 250 - minLength: 1 - type: string - description: | - The name of the field, shown on the storefront, orders, etc. Required for /POST - example: '1234567890123' - x-required: - - post - description: 'Gets custom fields associated with a product. These allow you to specify additional information that will appear on the product’s page, such as a book’s ISBN or a DVD’s release date.' - required: true - responses: - '200': - description: '' - content: - application/json: - schema: - type: object - properties: - data: - title: Custom Field - required: - - name - - value - type: object - properties: - id: - minimum: 1 - type: integer - description: |- - The unique numeric ID of the custom field; increments sequentially. - Read-Only - example: 6 - name: - maxLength: 250 - minLength: 1 - type: string - description: | - The name of the field, shown on the storefront, orders, etc. Required for /POST - example: ISBN - x-required: - - post - value: - maxLength: 250 - minLength: 1 - type: string - description: | - The name of the field, shown on the storefront, orders, etc. Required for /POST - example: '1234567890123' - x-required: - - post - description: 'Gets custom fields associated with a product. These allow you to specify additional information that will appear on the product’s page, such as a book’s ISBN or a DVD’s release date.' - meta: - $ref: '#/components/schemas/metaEmpty_Full' - example: - data: - name: Release Year - value: '1976' - id: 2 - meta: {} - '404': - description: | - The resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - '422': - description: | - The `CustomField` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - x-codegen-request-body-name: CustomField - delete: - tags: - - Product Custom Fields - summary: Delete a Custom Field - description: Deletes a product *Custom Field*. - operationId: deleteCustomFieldById - parameters: - - name: custom_field_id - in: path - description: | - The ID of the `CustomField`. - required: true - schema: - type: integer - responses: - '204': - description: '`204 No Content`. Action has been enacted and no further information is to be supplied. `null` is returned.' - content: {} - '404': - description: | - The resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - parameters: - - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/ProductIdParam' - - $ref: '#/components/parameters/CustomFieldIdParam' - '/catalog/products/{product_id}/bulk-pricing-rules': - get: - tags: - - Product Bulk Pricing Rules - summary: Get All Bulk Pricing Rules - description: Returns a list of *Bulk Pricing Rules*. Optional parameters can be passed in. - operationId: getBulkPricingRules - parameters: - - name: include_fields - in: query - description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' - schema: - type: string - - name: exclude_fields - in: query - description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' - schema: - type: string - - name: page - in: query - description: Specifies the page number in a limited (paginated) list of products. - schema: - type: integer - - name: limit - in: query - description: Controls the number of items per page in a limited (paginated) list of products. - schema: - type: integer - responses: - '200': - description: '' - content: - application/json: - schema: - type: object - properties: - data: - type: array - items: - allOf: - - type: object - properties: - id: - type: integer - description: Unique ID of the *Bulk Pricing Rule*. Read-Only. - readOnly: true - required: - - id - - $ref: '#/components/schemas/bulkPricingRule_Full' - meta: - $ref: '#/components/schemas/metaCollection_Full' - example: - data: - - id: 83 - quantity_min: 1 - quantity_max: 3 - type: price - amount: 1 - - id: 84 - quantity_min: 4 - quantity_max: 0 - type: price - amount: 1 - meta: - pagination: - total: 2 - count: 2 - per_page: 50 - current_page: 1 - total_pages: 1 - links: - current: '?page=1&limit=50' - '404': - description: | - The parent resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - post: - tags: - - Product Bulk Pricing Rules - summary: Create a Bulk Pricing Rule - description: |- - Creates a *Bulk Pricing Rule*. - - **Required Fields** - - quantity_min - - quantity_max - - type - - amount - - **Read-Only Fields** - - id - - **Limits** - - 50 bulk pricing rule per product limit. - operationId: createBulkPricingRule - parameters: - - $ref: '#/components/parameters/ContentType' - - name: page - in: query - description: Specifies the page number in a limited (paginated) list of products. - schema: - type: integer - - name: limit - in: query - description: Controls the number of items per page in a limited (paginated) list of products. - schema: - type: integer - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/bulkPricingRule_Full' - required: true - responses: - '200': - description: '' - content: - application/json: - schema: - type: object - properties: - data: - allOf: - - type: object - properties: - id: - type: integer - description: Unique ID of the *Bulk Pricing Rule*. Read-Only. - readOnly: true - required: - - id - - $ref: '#/components/schemas/bulkPricingRule_Full' - meta: - title: Meta - type: object - description: Empty meta object; may be used later. - example: - data: - id: 83 - quantity_min: 1 - quantity_max: 3 - type: price - amount: 1 - meta: {} - '404': - description: | - The parent resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - '409': - description: | - The `BulkPricingRule` was in conflict with another bulk pricing rule. This is the result of quantity range overlapping with existing bulk pricing rules. - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - '422': - description: | - The `BulkPricingRule` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - x-codegen-request-body-name: BulkPricingRule - parameters: - - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/ProductIdParam' - '/catalog/products/{product_id}/bulk-pricing-rules/{bulk_pricing_rule_id}': - get: - tags: - - Product Bulk Pricing Rules - summary: Get a Bulk Pricing Rule - description: Returns a single *Bulk Pricing Rule*. Optional parameters can be passed in. - operationId: getBulkPricingRuleById - parameters: - - name: bulk_pricing_rule_id - in: path - description: | - The ID of the `BulkPricingRule`. - required: true - schema: - type: integer - - - name: include_fields - in: query - description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' - schema: - type: string - - name: exclude_fields - in: query - description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' - schema: - type: string - responses: - '200': - description: '' - content: - application/json: - schema: - type: object - properties: - data: - allOf: - - type: object - properties: - id: - type: integer - description: Unique ID of the *Bulk Pricing Rule*. Read-Only. - readOnly: true - required: - - id - - $ref: '#/components/schemas/bulkPricingRule_Full' - meta: - $ref: '#/components/schemas/metaEmpty_Full' - example: - data: - id: 83 - quantity_min: 1 - quantity_max: 3 - type: price - amount: 1 - meta: {} - '404': - description: | - The resource or parent resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - put: - tags: - - Product Bulk Pricing Rules - summary: Update a Bulk Pricing Rule - description: |- - Updates a *Bulk Pricing Rule*. - - **Required Fields** - * none - - **Read-Only Fields** - - id - operationId: updateBulkPricingRule - parameters: - - $ref: '#/components/parameters/ContentType' - - name: bulk_pricing_rule_id - in: path - description: | - The ID of the `BulkPricingRule`. - required: true - schema: - type: integer - requestBody: - content: - application/json: - schema: - allOf: - - type: object - properties: - id: - type: integer - description: Unique ID of the *Bulk Pricing Rule*. Read-Only. - readOnly: true - required: - - id - - $ref: '#/components/schemas/bulkPricingRule_Full' - required: true - responses: - '200': - description: '' - content: - application/json: - schema: - type: object - properties: - data: - title: Bulk Pricing Rule - required: - - amount - - quantity_max - - quantity_min - - type - type: object - properties: - id: - type: integer - description: Unique ID of the *Bulk Pricing Rule*. Read-Only. - readOnly: true - quantity_min: - minimum: 0 - type: integer - description: | - The minimum inclusive quantity of a product to satisfy this rule. Must be greater than or equal to zero. - Required in /POST. - example: 10 - x-required: - - post - quantity_max: - minimum: 0 - type: integer - description: |- - The maximum inclusive quantity of a product to satisfy this rule. Must be greater than the `quantity_min` value – unless this field has a value of 0 (zero), in which case there will be no maximum bound for this rule. - Required in /POST. - example: 50 - x-required: - - post - type: - type: string - description: |- - The type of adjustment that is made. Values: `price` - the adjustment amount per product; `percent` - the adjustment as a percentage of the original price; `fixed` - the adjusted absolute price of the product. - Required in /POST. - example: price - enum: - - price - - percent - - fixed - x-required: - - post - amount: - type: integer - description: |- - The discount can be a fixed dollar amount or a percentage. For a fixed dollar amount enter it as an integer and the response will return as an integer. For percentage enter the amount as the percentage divided by 100 using string format. For example 10% percent would be “.10”. The response will return as an integer. - Required in /POST. - description: Common BulkPricingRule properties - meta: - $ref: '#/components/schemas/metaEmpty_Full' - example: - data: - id: 83 - quantity_min: 1 - quantity_max: 3 - type: price - amount: 1 - meta: {} - '404': - description: | - The resource or parent resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - '409': - description: | - The `BulkPricingRule` was in conflict with another bulk pricing rule. This is the result of quantity range overlapping with existing bulk pricing rules. - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - '422': - description: | - The `BulkPricingRule` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - x-codegen-request-body-name: BulkPricingRule - delete: - tags: - - Product Bulk Pricing Rules - summary: Delete a Bulk Pricing Rule - description: Deletes a *Bulk Pricing Rule*. - operationId: deleteBulkPricingRuleById - parameters: - - name: bulk_pricing_rule_id - in: path - description: | - The ID of the `BulkPricingRule`. - required: true - schema: - type: integer - responses: - '204': - description: '' - content: {} - '404': - description: | - The resource or parent resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - parameters: - - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/ProductIdParam' - - $ref: '#/components/parameters/BulkPricingRuleIdParam' - '/catalog/products/{product_id}/metafields': - get: - tags: - - Product Metafields - summary: Get All Product Metafields - description: Returns a list of *Product Metafields*. Optional parameters can be passed in. - operationId: getProductMetafieldsByProductId - parameters: - - name: page - in: query - description: Specifies the page number in a limited (paginated) list of products. - schema: - type: integer - - name: limit - in: query - description: Controls the number of items per page in a limited (paginated) list of products. - schema: - type: integer - - name: key - in: query - description: | - Filter based on a metafield's key. - schema: - type: string - - name: namespace - in: query - description: Filter based on a metafield's namespace. - schema: - type: string - - name: include_fields - in: query - description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' - schema: - type: string - - name: exclude_fields - in: query - description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' - schema: - type: string - responses: - '200': - description: '' - content: - application/json: - schema: - title: Meta Field Collection Response - type: object - properties: - data: - type: array - items: - $ref: '#/components/schemas/metafield_Full' - meta: - $ref: '#/components/schemas/metaCollection_Full' - example: - data: - - id: 6 - key: Location - value: 4HG - namespace: Warehouse Locations - permission_set: app_only - resource_type: product - resource_id: 111 - description: Location in the warehouse - date_created: '1973-01-20T21:34:57.903Z' - date_modified: '1990-12-30T00:29:23.515Z' - - id: 7 - key: Sublocation - value: 4HG - namespace: Warehouse Locations - permission_set: read - resource_type: product - resource_id: 111 - description: Location in the warehouse - date_created: '1973-01-20T21:34:57.903Z' - date_modified: '1990-12-30T00:29:23.515Z' - meta: - pagination: - total: 2 - count: 2 - per_page: 50 - current_page: 1 - total_pages: 1 - links: - current: '?page=1&limit=50' - '404': - description: | - The resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - post: - tags: - - Product Metafields - summary: Create a Product Metafield - description: |- - Creates a *Product Metafield*. - - **Required Fields:** - * permission_set - * namespace - * key - * value - - **Read-Only Fields** - * id - - **Note:** The maxiumum number of metafields allowed on each order, product, category, variant, or brand is 250 per client ID. For more information, see [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center. - operationId: createProductMetafield - parameters: - - $ref: '#/components/parameters/ContentType' - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/metafield_Base' - required: true - responses: - '200': - description: '' - content: - application/json: - schema: - title: Metafield Response - type: object - properties: - data: - $ref: '#/components/schemas/metafield_Full' - meta: - $ref: '#/components/schemas/metaEmpty_Full' - example: - data: - id: 8 - key: location_id - value: 'Shelf 3, Bin 5' - namespace: Inventory Namespace - permission_set: read - resource_type: product - resource_id: 158 - description: Where products are located - date_created: '2018-09-13T16:42:37+00:00' - date_modified: '2018-09-13T16:42:37+00:00' - meta: {} - '409': - description: | - The `Metafield` was in conflict with another `Metafield`. This can be the result of duplicate unique key combinations of the app's client id, namespace, key, resource_type, and resource_id. - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: |- - The HTTP status code. - title: - type: string - description: |- - The error title describing the particular error. - type: - type: string - '422': - description: | - The `Metafield` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - parameters: - - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/ProductIdParam' - '/catalog/products/{product_id}/metafields/{metafield_id}': - get: - tags: - - Product Metafields - summary: Get a Product Metafield - description: Returns a single *Product Metafield*. Optional parameters can be passed in. - operationId: getProductMetafieldByProductId - parameters: - - name: metafield_id - in: path - description: | - The ID of the `Metafield`. - required: true - schema: - type: integer - - - name: include_fields - in: query - description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' - schema: - type: string - - name: exclude_fields - in: query - description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' - schema: - type: string - responses: - '200': - description: '' - content: - application/json: - schema: - title: Metafield Response - type: object - properties: - data: - $ref: '#/components/schemas/metafield_Full' - meta: - $ref: '#/components/schemas/metaEmpty_Full' - example: - data: - id: 4 - key: location_id - value: 'Shelf 3, Bin 5' - namespace: App Namespace - permission_set: app_only - resource_type: product - resource_id: 137 - description: Where products are located - date_created: '2021-08-06T19:15:35+00:00' - date_modified: '2021-08-06T19:15:35+00:00' - meta: {} - '404': - description: | - The resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - put: - tags: - - Product Metafields - summary: Update a Product Metafield - description: "Updates a *Product Metafield*.\n\n**Required Fields**\n* none\n\n**Read-Only Fields**\n* id\n* These fields can only be modified using the API account that created the metafield:\n\t* `namespace`\n\t* `key`\n\t* `permission_set`\n\t* `value`\n\n**Usage Notes**\n* Attempting to modify the `namespace`, `key`, `permission_set`, or `value` field using an API account different from the one used to create those metafields will result in a `403` error message. " - operationId: updateProductMetafield - parameters: - - $ref: '#/components/parameters/ContentType' - - name: metafield_id - in: path - description: | - The ID of the `Metafield`. - required: true - schema: - type: integer - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/metafield_Base' - required: true - responses: - '200': - description: '' - content: - application/json: - schema: - title: Metafield Response - type: object - properties: - data: - $ref: '#/components/schemas/metafield_Full' - meta: - $ref: '#/components/schemas/metaEmpty_Full' - example: - data: - id: 4 - key: location_id - value: 'Shelf 3, Bin 5' - namespace: App Namespace - permission_set: app_only - resource_type: product - resource_id: 137 - description: Where products are located - date_created: '2021-08-06T19:15:35+00:00' - date_modified: '2021-08-06T19:15:35+00:00' - meta: {} - '404': - description: | - The resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - x-codegen-request-body-name: Metafield - delete: - tags: - - Product Metafields - summary: Delete a Product Metafield - description: Deletes a *Product Metafield*. - operationId: deleteProductMetafieldById - parameters: - - name: metafield_id - in: path - description: | - The ID of the `Metafield`. - required: true - schema: - type: integer - responses: - '204': - description: '' - content: {} - parameters: - - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/ProductIdParam' - - $ref: '#/components/parameters/MetafieldIdParam' - '/catalog/products/{product_id}/reviews': - get: - tags: - - Product Reviews - summary: Get Product Reviews - description: Returns a list of all *Product Reviews*. Optional parameters can be passed in. - operationId: getProductReviews - parameters: - - name: include_fields - in: query - description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' - schema: - type: string - - name: exclude_fields - in: query - description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' - schema: - type: string - - name: page - in: query - description: Specifies the page number in a limited (paginated) list of products. - schema: - type: integer - - name: limit - in: query - description: Controls the number of items per page in a limited (paginated) list of products. - schema: - type: integer - - name: status - in: query - description: 'Filter items by status. `1` for approved, `0` for pending.' - schema: - type: integer - responses: - '200': - description: '' - content: - application/json: - schema: - title: Product Review Collection Response - type: object - properties: - data: - type: array - items: - title: Product Review - type: object - description: | - A product review model. - allOf: - - title: Product Review Base - required: - - date_reviewed - - title - type: object - properties: - title: - maxLength: 255 - minLength: 0 - type: string - description: |- - The title for the product review. - Required in /POST. - text: - type: string - description: | - The text for the product review. - status: - type: string - description: | - The status of the product review. Must be one of `approved`, `disapproved` or `pending`. - rating: - type: integer - description: 'The rating of the product review. Must be one of 0, 1, 2, 3, 4, 5.' - email: - type: string - description: 'The email of the reviewer. Must be a valid email, or an empty string.' - name: - maxLength: 255 - minLength: 0 - type: string - description: The name of the reviewer. - date_reviewed: - type: string - description: | - Date the product was reviewed. Required in /POST. - format: date-time - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the product review; increments sequentially. - product_id: - type: integer - description: | - The unique numeric identifier for the product with which the review is associated. - date_created: - type: string - description: | - Date the product review was created. - format: date-time - date_modified: - type: string - description: | - Date the product review was modified. - format: date-time - meta: - $ref: '#/components/schemas/metaCollection_Full' - '204': - description: | - There are no reviews on this product. - content: {} - '404': - description: | - The product ID does not exist. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - post: - tags: - - Product Reviews - summary: Create a Product Review - description: |- - Creates a *Product Review*. - - **Required Fields** - - title - - date_reviewed - - **Read-Only Fields** - * id - operationId: createProductReview - parameters: - - $ref: '#/components/parameters/ContentType' - requestBody: - content: - application/json: - schema: - title: Product Review Post - description: | - The model for a POST to create a product review. - allOf: - - title: Product Review Base - required: - - date_reviewed - - title - type: object - properties: - title: - maxLength: 255 - minLength: 0 - type: string - description: |- - The title for the product review. - Required in /POST. - text: - type: string - description: | - The text for the product review. - status: - type: string - description: | - The status of the product review. Must be one of `approved`, `disapproved` or `pending`. - rating: - type: integer - description: 'The rating of the product review. Must be one of 0, 1, 2, 3, 4, 5.' - email: - type: string - description: 'The email of the reviewer. Must be a valid email, or an empty string.' - name: - maxLength: 255 - minLength: 0 - type: string - description: The name of the reviewer. - date_reviewed: - type: string - description: | - Date the product was reviewed. Required in /POST. - format: date-time - required: true - responses: - '200': - description: '' - content: - application/json: - schema: - title: Product Review Response - type: object - properties: - data: - title: Product Review - type: object - description: | - A product review model. - allOf: - - title: Product Review Base - required: - - date_reviewed - - title - type: object - properties: - title: - maxLength: 255 - minLength: 0 - type: string - description: |- - The title for the product review. - Required in /POST. - text: - type: string - description: | - The text for the product review. - status: - type: string - description: | - The status of the product review. Must be one of `approved`, `disapproved` or `pending`. - rating: - type: integer - description: 'The rating of the product review. Must be one of 0, 1, 2, 3, 4, 5.' - email: - type: string - description: 'The email of the reviewer. Must be a valid email, or an empty string.' - name: - maxLength: 255 - minLength: 0 - type: string - description: The name of the reviewer. - date_reviewed: - type: string - description: | - Date the product was reviewed. Required in /POST. - format: date-time - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the product review; increments sequentially. - product_id: - type: integer - description: | - The unique numeric identifier for the product with which the review is associated. - date_created: - type: string - description: | - Date the product review was created. - format: date-time - date_modified: - type: string - description: | - Date the product review was modified. - format: date-time - meta: - $ref: '#/components/schemas/metaEmpty_Full' - description: | - Response payload for the BigCommerce API. - example: - data: - title: irur - text: anim aute - status: Lorem ad sed voluptate - rating: 3 - email: esse Lorem laborum aute - name: 'ut in ' - date_reviewed: '2011-12-31T13:40:42.971Z' - id: 82495037 - product_id: 22609026 - date_created: '1985-01-17T07:37:20.439Z' - date_modified: '2004-09-28T14:38:21.973Z' - meta: {} - '404': - description: | - The product ID does not exist. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - x-codegen-request-body-name: productReview - parameters: - - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/ProductIdParam' - '/catalog/products/{product_id}/reviews/{review_id}': - get: - tags: - - Product Reviews - summary: Get a Product Review - description: Returns a single *Product Review*. Optional parameters maybe passed in. - operationId: getProductReviewById - parameters: - - name: review_id - in: path - description: | - The ID of the `review` that is being operated on. - required: true - schema: - type: integer - - - name: include_fields - in: query - description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' - schema: - type: string - - name: exclude_fields - in: query - description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' - schema: - type: string - responses: - '200': - description: '' - content: - application/json: - schema: - title: Product Review Response - type: object - properties: - data: - title: Product Review - type: object - description: | - A product review model. - allOf: - - title: Product Review Base - required: - - date_reviewed - - title - type: object - properties: - title: - maxLength: 255 - minLength: 0 - type: string - description: |- - The title for the product review. - Required in /POST. - text: - type: string - description: | - The text for the product review. - status: - type: string - description: | - The status of the product review. Must be one of `approved`, `disapproved` or `pending`. - rating: - type: integer - description: 'The rating of the product review. Must be one of 0, 1, 2, 3, 4, 5.' - email: - type: string - description: 'The email of the reviewer. Must be a valid email, or an empty string.' - name: - maxLength: 255 - minLength: 0 - type: string - description: The name of the reviewer. - date_reviewed: - type: string - description: | - Date the product was reviewed. Required in /POST. - format: date-time - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the product review; increments sequentially. - date_created: - type: string - description: | - Date the product review was created. - format: date-time - date_modified: - type: string - description: | - Date the product review was modified. - format: date-time - meta: - $ref: '#/components/schemas/metaEmpty_Full' - description: | - Response payload for the BigCommerce API. - example: - data: - title: irur - text: anim aute - status: Lorem ad sed voluptate - rating: 3 - email: esse Lorem laborum aute - name: 'ut in ' - date_reviewed: '2011-12-31T13:40:42.971Z' - id: 82495037 - product_id: 22609026 - date_created: '1985-01-17T07:37:20.439Z' - date_modified: '2004-09-28T14:38:21.973Z' - meta: {} - '404': - description: | - The resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - put: - tags: - - Product Reviews - summary: Update a Product Review - description: |- - Updates a *Product Review*. - - **Required Fields** - * none - - **Read-Only Fields** - * id - operationId: updateProductReview - parameters: - - $ref: '#/components/parameters/ContentType' - - name: review_id - in: path - description: | - The ID of the `review` that is being operated on. - required: true - schema: - type: integer - requestBody: - description: | - A BigCommerce `ProductReview` object. - content: - application/json: - schema: - title: Product Review Put - description: | - The model for a PUT to update a product review. - allOf: - - title: Product Review Base - required: - - date_reviewed - - title - type: object - properties: - title: - maxLength: 255 - minLength: 0 - type: string - description: |- - The title for the product review. - Required in /POST. - text: - type: string - description: | - The text for the product review. - status: - type: string - description: | - The status of the product review. Must be one of `approved`, `disapproved` or `pending`. - rating: - type: integer - description: 'The rating of the product review. Must be one of 0, 1, 2, 3, 4, 5.' - email: - type: string - description: 'The email of the reviewer. Must be a valid email, or an empty string.' - name: - maxLength: 255 - minLength: 0 - type: string - description: The name of the reviewer. - date_reviewed: - type: string - description: | - Date the product was reviewed. Required in /POST. - format: date-time - required: true - responses: - '200': - description: '' - content: - application/json: - schema: - title: Product Review Response - type: object - properties: - data: - title: Product Review - type: object - description: | - A product review model. - allOf: - - title: Product Review Base - required: - - date_reviewed - - title - type: object - properties: - title: - maxLength: 255 - minLength: 0 - type: string - description: |- - The title for the product review. - Required in /POST. - text: - type: string - description: | - The text for the product review. - status: - type: string - description: | - The status of the product review. Must be one of `approved`, `disapproved` or `pending`. - rating: - type: integer - description: 'The rating of the product review. Must be one of 0, 1, 2, 3, 4, 5.' - email: - type: string - description: 'The email of the reviewer. Must be a valid email, or an empty string.' - name: - maxLength: 255 - minLength: 0 - type: string - description: The name of the reviewer. - date_reviewed: - type: string - description: | - Date the product was reviewed. Required in /POST. - format: date-time - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the product review; increments sequentially. - product_id: - type: integer - description: | - The unique numeric identifier for the product with which the review is associated. - date_created: - type: string - description: | - Date the product review was created. - format: date-time - date_modified: - type: string - description: | - Date the product review was modified. - format: date-time - meta: - $ref: '#/components/schemas/metaEmpty_Full' - description: | - Response payload for the BigCommerce API. - example: - data: - title: irur - text: anim aute - status: Lorem ad sed voluptate - rating: 3 - email: esse Lorem laborum aute - name: 'ut in ' - date_reviewed: '2011-12-31T13:40:42.971Z' - id: 82495037 - product_id: 22609026 - date_created: '1985-01-17T07:37:20.439Z' - date_modified: '2004-09-28T14:38:21.973Z' - meta: {} - '404': - description: | - The resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - x-codegen-request-body-name: productReview - delete: - tags: - - Product Reviews - summary: Delete a Product Review - description: Deletes a *Product Review*. - operationId: deleteProductReview - parameters: - - name: review_id - in: path - description: | - The ID of the `review` that is being operated on. - required: true - schema: - type: integer - responses: - '204': - description: '' - content: {} - parameters: - - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/ProductIdParam' - - $ref: '#/components/parameters/ReviewIdParam' - '/catalog/categories': - get: - tags: - - Category - summary: Get All Categories - description: Returns a list of *Categories*. Optional filter parameters can be passed in. - operationId: getCategories - parameters: - - name: id - in: query - description: | - Filter items by id. - schema: - type: integer - - name: 'id:in' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: 'id:not_in' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: 'id:min' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: 'id:max' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: 'id:greater' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: 'id:less' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: name - in: query - description: | - Filter items by name. - schema: - type: string - - name: 'name:like' - in: query - style: form - explode: false - schema: - type: array - items: - type: string - - name: parent_id - in: query - description: 'Filter items by parent_id. If the category is a child or sub category it can be filtered with the parent_id. ' - schema: - type: integer - - name: 'parent_id:in' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: 'parent_id:min' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: 'parent_id:max' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: 'parent_id:greater' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: 'parent_id:less' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: page_title - in: query - description: | - Filter items by page_title. - schema: - type: string - - name: 'page_title:like' - in: query - style: form - explode: false - schema: - type: array - items: - type: string - - name: keyword - in: query - description: 'Filter items by keywords. eg. new, towel, bath' - schema: - type: string - - name: is_visible - in: query - description: 'Filter items by if visible on the storefront. ' - schema: - type: boolean - - name: page - in: query - description: Specifies the page number in a limited (paginated) list of products. - schema: - type: integer - - name: limit - in: query - description: Controls the number of items per page in a limited (paginated) list of products. - schema: - type: integer - - name: include_fields - in: query - description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' - schema: - type: string - - name: exclude_fields - in: query - description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' - schema: - type: string - responses: - '200': - description: '' - content: - application/json: - schema: - title: Category Base - type: object - properties: - data: - type: array - items: - $ref: '#/components/schemas/Category' - meta: - $ref: '#/components/schemas/metaCollection_Full' - example: - data: - - id: 19 - parent_id: 0 - name: Garden - description: <p>This is the garden description</p> - views: 0 - sort_order: 2 - page_title: page title - meta_keywords: - - meta keyword - meta_description: meta description - layout_file: category.html - image_url: '' - is_visible: true - search_keywords: search keywords - default_product_sort: use_store_settings - custom_url: - url: /garden/ - is_customized: false - - id: 20 - parent_id: 0 - name: Publications - description: '' - views: 0 - sort_order: 4 - page_title: '' - meta_keywords: - - '' - meta_description: '' - layout_file: category_with_facets.html - image_url: '' - is_visible: true - search_keywords: '' - default_product_sort: use_store_settings - custom_url: - url: /publications/ - is_customized: false - - id: 21 - parent_id: 0 - name: Kitchen - description: '' - views: 0 - sort_order: 3 - page_title: '' - meta_keywords: - - '' - meta_description: '' - layout_file: category_with_facets.html - image_url: '' - is_visible: true - search_keywords: '' - default_product_sort: use_store_settings - custom_url: - url: /kitchen/ - is_customized: false - - id: 22 - parent_id: 0 - name: Utility - description: '' - views: 0 - sort_order: 5 - page_title: '' - meta_keywords: - - '' - meta_description: '' - layout_file: category_with_facets.html - image_url: '' - is_visible: true - search_keywords: '' - default_product_sort: use_store_settings - custom_url: - url: /utility/ - is_customized: false - - id: 23 - parent_id: 0 - name: Shop All - description: '' - views: 0 - sort_order: 0 - page_title: '' - meta_keywords: - - '' - meta_description: '' - layout_file: category_with_facets.html - image_url: '' - is_visible: true - search_keywords: '' - default_product_sort: use_store_settings - custom_url: - url: /shop-all/ - is_customized: false - - id: 39 - parent_id: 19 - name: Bath - description: '' - views: 0 - sort_order: 0 - page_title: '' - meta_keywords: - - '' - meta_description: '' - layout_file: category.html - image_url: '' - is_visible: true - search_keywords: '' - default_product_sort: use_store_settings - custom_url: - url: /garden/bath/ - is_customized: false - meta: - pagination: - total: 6 - count: 6 - per_page: 50 - current_page: 1 - total_pages: 1 - links: - current: '?page=1&limit=50' - post: - tags: - - Category - summary: Create a Category - description: "Creates a *Category*.\n\nUse this endpoint when an API only works with categories of a default BigCommerce storefront (`channel_id=1`). \n\nUse the [Create Categories](/docs/rest-management/catalog/categories-batch#create-categories) endpoint when an API works with categories across different category trees that belong to different storefront channels.\n\n**Required Fields**:\n- `parent_id`: \n\t- To create a child category, set the `parent_id` to the parent category.\n\t- To create a top level category, set the `parent_id` to `0`.\n- `name`\n\n**Read-Only Fields**:\n- `id`\n\n**Limits**:\n- 16,000 categories per store limit.\n- 1,000 categories per product limit.\n- 50 characters category name length.\n- 8 levels of category depth limit.\n- 65,642 characters category description length limit." - operationId: createCategory - parameters: - - $ref: '#/components/parameters/ContentType' - requestBody: - content: - application/json: - schema: - title: Category - type: object - description: Common Category object properties. - properties: - parent_id: - type: integer - description: |- - The unique numeric ID of the category's parent. This field controls where the category sits in the tree of categories that organize the catalog. - Required in a POST if creating a child category. - example: 2 - x-required: - - post - name: - maxLength: 50 - minLength: 1 - type: string - description: |- - The name displayed for the category. Name is unique with respect to the category's siblings. - Required in a POST. - example: Bath - x-required: - - post - description: - type: string - description: | - The product description, which can include HTML formatting. - example: <p>We offer a wide variety of products perfect for relaxing</p> - views: - type: integer - description: | - Number of views the category has on the storefront. - example: 1050 - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - Priority this category will be given when included in the menu and category pages. The lower the number, the closer to the top of the results the category will be. - example: 3 - page_title: - maxLength: 255 - minLength: 0 - type: string - description: | - Custom title for the category page. If not defined, the category name will be used as the meta title. - example: Bath - search_keywords: - maxLength: 255 - minLength: 0 - type: string - description: | - A comma-separated list of keywords that can be used to locate the category when searching the store. - meta_keywords: - type: array - description: | - Custom meta keywords for the category page. If not defined, the store's default keywords will be used. Must post as an array like: ["awesome","sauce"]. - items: - type: string - meta_description: - maxLength: 65535 - minLength: 0 - type: string - description: | - Custom meta description for the category page. If not defined, the store's default meta description will be used. - layout_file: - maxLength: 500 - minLength: 0 - type: string - description: | - A valid layout file. (Please refer to [this article](https://support.bigcommerce.com/articles/Public/Creating-Custom-Template-Files/) on creating category files.) This field is writable only for stores with a Blueprint theme applied. For stores with a Stencil theme applied, see [Custom Template Associations](https://developer.bigcommerce.com/api-reference/store-management/custom-template-associations). - example: category.html - is_visible: - type: boolean - description: | - Flag to determine whether the category should be displayed to customers browsing the store. If `true`, the category will be displayed. If `false`, the category will be hidden from view. - default_product_sort: - type: string - description: | - Determines how the products are sorted on category page load. - enum: - - use_store_settings - - featured - - newest - - best_selling - - alpha_asc - - alpha_desc - - avg_customer_review - - price_asc - - price_desc - image_url: - type: string - description: | - Image URL used for this category on the storefront. Images can be uploaded via form file post to `/categories/{categoryId}/image`, or by providing a publicly accessible URL in this field. - example: 'https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png' - x-url: true - custom_url: - title: Custom Url Category - type: object - description: The custom URL for the category on the storefront. - properties: - url: - maxLength: 255 - minLength: 0 - type: string - description: | - Category URL on the storefront. - example: /shoes - x-required: - - post - - put - x-url: true - is_customized: - type: boolean - description: | - Returns `true` if the URL has been changed from its default state (the auto-assigned URL that BigCommerce provides). - x-required: - - post - - put - required: - - parent_id - - name - required: true - responses: - '200': - description: '' - content: - application/json: - schema: - title: Category Response - type: object - properties: - data: - $ref: '#/components/schemas/category_Full' - meta: - $ref: '#/components/schemas/metaEmpty_Full' - '207': - description: 'Multiple operations have taken place and the status for each operation can be viewed in the body of the response. Typically indicates that a partial failure has occured, such as when a `POST` or `PUT` request is successful, but saving the URL has failed.' - content: - application/json: - schema: - $ref: '#/components/schemas/error_Base' - '409': - description: | - The `Category` was in conflict with another category. This is the result of duplicate unique values, such as `name` or `custom_url`. - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - '422': - description: | - The `Category` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - x-codegen-request-body-name: category - delete: - tags: - - Category - summary: Delete Categories - description: |- - Deletes *Category* objects. At least one filter parameter is required to perform the `DELETE` operation. - - **Usage Notes** - - - Sending a `DELETE`request without specifying a filter parameter will result in a `422` error. - - Sending a `DELETE` request for a category that contains products will result in a `422` error. Move products to a new category by sending a `PUT` request to the `/catalog/products/{product_id}` endpoint before deleting a category. - operationId: deleteCategories - parameters: - - name: id - in: query - description: Filter items by id. - schema: - type: integer - - name: 'id:in' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: 'id:not_in' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: 'id:min' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: 'id:max' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: 'id:greater' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: 'id:less' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: name - in: query - description: | - Filter items by name. - schema: - type: string - - name: parent_id - in: query - description: 'Filter items by parent_id. If the category is a child or sub category it can be filtered with the parent_id. ' - schema: - type: integer - - name: page_title - in: query - description: | - Filter items by page_title. - schema: - type: string - - name: keyword - in: query - description: 'Filter items by keywords. eg. new, towel, bath' - schema: - type: string - - name: is_visible - in: query - description: 'Filter items by if visible on the storefront. ' - schema: - type: boolean - - name: 'name:like' - in: query - style: form - explode: false - schema: - type: array - items: - type: string - - name: 'parent_id:in' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: 'parent_id:min' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: 'parent_id:max' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: 'parent_id:greater' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: 'parent_id:less' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: 'page_title:like' - in: query - style: form - explode: false - schema: - type: array - items: - type: string - responses: - '204': - description: '' - content: {} - parameters: - - $ref: '#/components/parameters/Accept' - '/catalog/categories/{category_id}': - get: - tags: - - Category - summary: Get a Category - description: Returns a single *Category*. Optional parameters can be passed in. - operationId: getCategoryById - parameters: - - name: category_id - in: path - description: | - The ID of the `Category` to which the resource belongs. - required: true - schema: - type: integer - - - name: include_fields - in: query - description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' - schema: - type: string - - name: exclude_fields - in: query - description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' - schema: - type: string - responses: - '200': - description: '' - content: - application/json: - schema: - title: Category Response - type: object - properties: - data: - $ref: '#/components/schemas/category_Full' - meta: - $ref: '#/components/schemas/metaEmpty_Full' - '404': - description: | - The resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - put: - tags: - - Category - summary: Update a Category - description: |- - Updates a *Category*. - - **Required Fields** - * none - - **Read-Only Fields** - - id - operationId: updateCategory - parameters: - - $ref: '#/components/parameters/ContentType' - - name: category_id - in: path - description: | - The ID of the `Category` to which the resource belongs. - required: true - schema: - type: integer - requestBody: - content: - application/json: - schema: - title: Category - type: object - description: Common Category object properties. - properties: - id: - type: integer - description: |- - Unique ID of the *Category*. Increments sequentially. - Read-Only. - readOnly: true - parent_id: - type: integer - description: |- - The unique numeric ID of the category's parent. This field controls where the category sits in the tree of categories that organize the catalog. - Required in a POST if creating a child category. - example: 2 - x-required: - - post - name: - maxLength: 50 - minLength: 1 - type: string - description: |- - The name displayed for the category. Name is unique with respect to the category's siblings. - Required in a POST. - example: Bath - x-required: - - post - description: - type: string - description: | - The product description, which can include HTML formatting. - example: <p>We offer a wide variety of products perfect for relaxing</p> - views: - type: integer - description: | - Number of views the category has on the storefront. - example: 1050 - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - Priority this category will be given when included in the menu and category pages. The lower the number, the closer to the top of the results the category will be. - example: 3 - page_title: - maxLength: 255 - minLength: 0 - type: string - description: | - Custom title for the category page. If not defined, the category name will be used as the meta title. - example: Bath - search_keywords: - maxLength: 255 - minLength: 0 - type: string - description: | - A comma-separated list of keywords that can be used to locate the category when searching the store. - meta_keywords: - type: array - description: | - Custom meta keywords for the category page. If not defined, the store's default keywords will be used. Must post as an array like: ["awesome","sauce"]. - items: - type: string - meta_description: - maxLength: 65535 - minLength: 0 - type: string - description: | - Custom meta description for the category page. If not defined, the store's default meta description will be used. - layout_file: - maxLength: 500 - minLength: 0 - type: string - description: | - A valid layout file. (Please refer to [this article](https://support.bigcommerce.com/articles/Public/Creating-Custom-Template-Files/) on creating category files.) This field is writable only for stores with a Blueprint theme applied. For stores with a Stencil theme applied, see [Custom Template Associations](https://developer.bigcommerce.com/api-reference/store-management/custom-template-associations). - example: category.html - is_visible: - type: boolean - description: | - Flag to determine whether the product should be displayed to customers browsing the store. If `true`, the category will be displayed. If `false`, the category will be hidden from view. - default_product_sort: - type: string - description: | - Determines how the products are sorted on category page load. - enum: - - use_store_settings - - featured - - newest - - best_selling - - alpha_asc - - alpha_desc - - avg_customer_review - - price_asc - - price_desc - image_url: - type: string - description: | - Image URL used for this category on the storefront. Images can be uploaded via form file post to `/categories/{categoryId}/image`, or by providing a publicly accessible URL in this field. - example: 'https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png' - x-url: true - custom_url: - title: Custom Url Category - type: object - description: The custom URL for the category on the storefront. - properties: - url: - maxLength: 255 - minLength: 0 - type: string - description: | - Category URL on the storefront. - example: /shoes - x-required: - - post - - put - x-url: true - is_customized: - type: boolean - description: | - Returns `true` if the URL has been changed from its default state (the auto-assigned URL that BigCommerce provides). - x-required: - - post - - put - required: - - parent_id - - name - required: true - responses: - '200': - description: '' - content: - application/json: - schema: - title: Category Response - type: object - properties: - data: - title: Category - type: object - description: Common Category object properties. - properties: - id: - type: integer - description: |- - Unique ID of the *Category*. Increments sequentially. - Read-Only. - readOnly: true - parent_id: - type: integer - description: |- - The unique numeric ID of the category's parent. This field controls where the category sits in the tree of categories that organize the catalog. - Required in a POST if creating a child category. - example: 2 - x-required: - - post - name: - maxLength: 50 - minLength: 1 - type: string - description: |- - The name displayed for the category. Name is unique with respect to the category's siblings. - Required in a POST. - example: Bath - x-required: - - post - description: - type: string - description: | - The product description, which can include HTML formatting. - example: <p>We offer a wide variety of products perfect for relaxing</p> - views: - type: integer - description: | - Number of views the category has on the storefront. - example: 1050 - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - Priority this category will be given when included in the menu and category pages. The lower the number, the closer to the top of the results the category will be. - example: 3 - page_title: - maxLength: 255 - minLength: 0 - type: string - description: | - Custom title for the category page. If not defined, the category name will be used as the meta title. - example: Bath - search_keywords: - maxLength: 255 - minLength: 0 - type: string - description: | - A comma-separated list of keywords that can be used to locate the category when searching the store. - meta_keywords: - type: array - description: | - Custom meta keywords for the category page. If not defined, the store's default keywords will be used. Must post as an array like: ["awesome","sauce"]. - items: - type: string - meta_description: - maxLength: 65535 - minLength: 0 - type: string - description: | - Custom meta description for the category page. If not defined, the store's default meta description will be used. - layout_file: - maxLength: 500 - minLength: 0 - type: string - description: | - A valid layout file. (Please refer to [this article](https://support.bigcommerce.com/articles/Public/Creating-Custom-Template-Files/) on creating category files.) This field is writable only for stores with a Blueprint theme applied. For stores with a Stencil theme applied, see [Custom Template Associations](https://developer.bigcommerce.com/api-reference/store-management/custom-template-associations). - example: category.html - is_visible: - type: boolean - description: | - Flag to determine whether the product should be displayed to customers browsing the store. If `true`, the category will be displayed. If `false`, the category will be hidden from view. - default_product_sort: - type: string - description: | - Determines how the products are sorted on category page load. - enum: - - use_store_settings - - featured - - newest - - best_selling - - alpha_asc - - alpha_desc - - avg_customer_review - - price_asc - - price_desc - image_url: - type: string - description: | - Image URL used for this category on the storefront. Images can be uploaded via form file post to `/categories/{categoryId}/image`, or by providing a publicly accessible URL in this field. - example: 'https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png' - x-url: true - custom_url: - title: Custom Url Category - type: object - description: The custom URL for the category on the storefront. - properties: - url: - maxLength: 255 - minLength: 0 - type: string - description: | - Category URL on the storefront. - example: /shoes - x-required: - - post - - put - x-url: true - is_customized: - type: boolean - description: | - Returns `true` if the URL has been changed from its default state (the auto-assigned URL that BigCommerce provides). - x-required: - - post - - put - required: - - parent_id - - name - meta: - title: Meta - type: object - description: Empty meta object; may be used later. - '207': - $ref: '#/components/responses/General207Status' - '404': - description: The resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - '409': - description: 'The `Category` was in conflict with another category. This is the result of duplicate unique values, such as `name` or `custom_url`.' - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - '422': - description: 'The `Category` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details.' - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - x-codegen-request-body-name: category - delete: - tags: - - Category - summary: Delete a Category - description: Deletes a *Category*. - operationId: deleteCategoryById - parameters: - - name: category_id - in: path - description: | - The ID of the `Category` to which the resource belongs. - required: true - schema: - type: integer - responses: - '204': - description: '' - content: {} - parameters: - - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/CategoryIdParam' - '/catalog/categories/{category_id}/metafields': - get: - tags: - - Category Metafields - summary: Get All Category Metafields - description: Returns a list of *Metafields* on a *Category*. Optional filter parameters can be passed in. - operationId: getCategoryMetafieldsByCategoryId - parameters: - - name: category_id - in: path - description: | - The ID of the `Category` to which the resource belongs. - required: true - schema: - type: integer - - - name: id - in: query - description: | - Filter items by id. - schema: - type: integer - - name: 'id:in' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: 'id:not_in' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: 'id:min' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: 'id:max' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: 'id:greater' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: 'id:less' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: page - in: query - description: Specifies the page number in a limited (paginated) list of products. - schema: - type: integer - - name: limit - in: query - description: Controls the number of items per page in a limited (paginated) list of products. - schema: - type: integer - - name: key - in: query - description: | - Filter based on a metafield's key. - schema: - type: string - - name: namespace - in: query - description: Filter based on a metafield's namespace. - schema: - type: string - - name: include_fields - in: query - description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' - schema: - type: string - - name: exclude_fields - in: query - description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' - schema: - type: string - responses: - '200': - description: '' - content: - application/json: - schema: - title: Meta Field Collection Response - type: object - properties: - data: - type: array - items: - $ref: '#/components/schemas/metafield_Full' - meta: - $ref: '#/components/schemas/metaCollection_Full' - example: - data: - - id: 6 - key: Location - value: 4HG - namespace: Warehouse Locations - permission_set: app_only - resource_type: category - resource_id: 111 - description: Location in the warehouse - date_created: '1973-01-20T21:34:57.903Z' - date_modified: '1990-12-30T00:29:23.515Z' - - id: 7 - key: Location - value: 4HG - namespace: Warehouse Locations - permission_set: read - resource_type: category - resource_id: 111 - description: Location in the warehouse - date_created: '1973-01-20T21:34:57.903Z' - date_modified: '1990-12-30T00:29:23.515Z' - meta: - pagination: - total: 2 - count: 2 - per_page: 50 - current_page: 1 - total_pages: 1 - links: - current: '?page=1&limit=50' - '404': - description: | - The resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - post: - tags: - - Category Metafields - summary: Create a Category Metafield - description: |- - Creates a *Category Metafield*. - - **Required Fields:** - - permission_set - - namespace - - key - - value - - **Read-Only Fields** - - id - - **Note:** The maxiumum number of metafields allowed on each order, product, category, variant, or brand is 250 per client ID. For more information, see [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center. - operationId: createCategoryMetafield - parameters: - - $ref: '#/components/parameters/ContentType' - - name: category_id - in: path - description: | - The ID of the `Category` to which the resource belongs. - required: true - schema: - type: integer - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/metafield_Base' - required: true - responses: - '200': - description: '' - content: - application/json: - schema: - title: Metafield Response - type: object - properties: - data: - $ref: '#/components/schemas/metafield_Full' - meta: - $ref: '#/components/schemas/metaEmpty_Full' - example: - data: - id: 4 - key: location_id - value: 'Shelf 3, Bin 5' - namespace: App Namespace - permission_set: app_only - resource_type: category - resource_id: 137 - description: Where products are located - date_created: '2021-08-06T19:15:35+00:00' - date_modified: '2021-08-06T19:15:35+00:00' - meta: {} - '409': - description: | - The `Metafield` was in conflict with another `Metafield`. This can be the result of duplicate, unique key combinations of the app's client id, namespace, key, resource_type, and resource_id. - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - '422': - description: | - The `Metafield` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - x-codegen-request-body-name: Metafield - parameters: - - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/CategoryIdParam' - '/catalog/categories/{category_id}/metafields/{metafield_id}': - get: - tags: - - Category Metafields - summary: Get a Category Metafield - description: Returns a single *Category Metafield*. Optional parameters can be passed in. - operationId: getCategoryMetafieldByCategoryId - parameters: - - name: metafield_id - in: path - description: | - The ID of the `Metafield`. - required: true - schema: - type: integer - - name: category_id - in: path - description: | - The ID of the `Category` to which the resource belongs. - required: true - schema: - type: integer - - - name: include_fields - in: query - description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' - schema: - type: string - - name: exclude_fields - in: query - description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' - schema: - type: string - responses: - '200': - description: '' - content: - application/json: - schema: - title: Metafield Response - type: object - properties: - data: - $ref: '#/components/schemas/metafield_Full' - meta: - $ref: '#/components/schemas/metaEmpty_Full' - example: - data: - id: 4 - key: location_id - value: 'Shelf 3, Bin 5' - namespace: App Namespace - permission_set: app_only - resource_type: category - resource_id: 137 - description: Where products are located - date_created: '2021-08-06T19:15:35+00:00' - date_modified: '2021-08-06T19:15:35+00:00' - meta: {} - '404': - description: The resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - put: - tags: - - Category Metafields - summary: Update a Category Metafield - description: "Updates a *Category Metafield*.\n\n**Required Fields**\n* none\n\n**Read-Only Fields**\n* id\n* These fields can only be modified by the app (API credentials) that created the metafield:\n\t* namespace\n\t* key\n\t* permission_set\n\n**Usage Notes**\n* Attempting to modify `namespace`, `key`, and `permission_set` fields using a client ID different from the one used to create those metafields will result in a 403 error message. " - operationId: updateCategoryMetafield - parameters: - - $ref: '#/components/parameters/ContentType' - - name: metafield_id - in: path - description: | - The ID of the `Metafield`. - required: true - schema: - type: integer - - name: category_id - in: path - description: | - The ID of the `Category` to which the resource belongs. - required: true - schema: - type: integer - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/metafield_Base' - required: true - responses: - '200': - description: '' - content: - application/json: - schema: - title: Metafield Response - type: object - properties: - data: - $ref: '#/components/schemas/metafield_Full' - meta: - $ref: '#/components/schemas/metaEmpty_Full' - example: - data: - id: 4 - key: location_id - value: 'Shelf 3, Bin 5' - namespace: App Namespace - permission_set: app_only - resource_type: category - resource_id: 137 - description: Where products are located - date_created: '2021-08-06T19:15:35+00:00' - date_modified: '2021-08-06T19:15:35+00:00' - meta: {} - '404': - description: | - The resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - x-codegen-request-body-name: Metafield - delete: - tags: - - Category Metafields - summary: Delete a Category Metafield - description: Deletes a *Category Metafield*. - operationId: deleteCategoryMetafieldById - parameters: - - name: metafield_id - in: path - description: | - The ID of the `Metafield`. - required: true - schema: - type: integer - - name: category_id - in: path - description: | - The ID of the `Category` to which the resource belongs. - required: true - schema: - type: integer - responses: - '204': - description: '' - content: {} - parameters: - - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/CategoryIdParam' - - $ref: '#/components/parameters/MetafieldIdParam' - '/catalog/categories/{category_id}/image': - post: - tags: - - Category Images - summary: Create a Category Image - description: |- - Create a *Category Image*. - - **Required Fields** - - image_file: Form posts are the only accepted upload option. - - Only one image at a time can be created. - Limit image size to 1MB. - To update a *Category Image*, use the [Update categories](/docs/rest-management/catalog/categories-batch#update-categories) endpoint and an `image_url`. - operationId: createCategoryImage - parameters: - - $ref: '#/components/parameters/ContentType' - - name: category_id - in: path - description: | - The ID of the `Category` to which the resource belongs. - required: true - schema: - type: integer - requestBody: - content: - multipart/form-data: - schema: - type: object - properties: - image_file: - type: string - format: binary - responses: - '200': - description: '' - content: - application/json: - schema: - type: object - properties: - data: - type: object - properties: - image_url: - type: string - meta: - $ref: '#/components/schemas/metaEmpty_Full' - example: - data: - image_url: 'https://cdn11.bigcommerce.com/s-{store_hash}/product_images/k/group_1545334669__76009.png' - meta: {} - '400': - description: Bad Request. The requested resource could not be downloaded and may be invalid. Possible reasons include malformed request syntax or the file host blocking requests. - content: - application/json: - schema: - type: object - properties: {} - '404': - description: | - The resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - '422': - description: | - Image was not valid. This is the result of a missing `image_file` field or an incorrect file type. See the response for more details. - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - delete: - tags: - - Category Images - summary: Delete a Category Image - description: Deletes a *Cateogory Image*. - operationId: deleteCategoryImage - parameters: - - name: category_id - in: path - description: | - The ID of the `Category` to which the resource belongs. - required: true - schema: - type: integer - responses: - '204': - description: '' - content: {} - parameters: - - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/CategoryIdParam' - '/catalog/brands': - get: - tags: - - Brands - summary: Get All Brands - description: Returns a list of *Brands*. Optional filter parameters can be passed in. - operationId: getBrands - parameters: - - name: id - in: query - description: | - Filter items by id. - schema: - type: integer - - name: 'id:in' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: 'id:not_in' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: 'id:min' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: 'id:max' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: 'id:greater' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: 'id:less' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: name - in: query - description: | - Filter items by name. - schema: - type: string - - name: page_title - in: query - description: | - Filter items by page_title. - schema: - type: string - - name: page - in: query - description: Specifies the page number in a limited (paginated) list of products. - schema: - type: integer - - name: limit - in: query - description: Controls the number of items per page in a limited (paginated) list of products. - schema: - type: integer - - name: include_fields - in: query - description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' - schema: - type: string - - name: exclude_fields - in: query - description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' - schema: - type: string - responses: - '200': - description: '' - content: - application/json: - schema: - title: Brand Collection Response - type: object - properties: - data: - type: array - items: - $ref: '#/components/schemas/brand_Full' - meta: - $ref: '#/components/schemas/metaCollection_Full' - example: - data: - - id: 35 - name: Sagaform - page_title: '' - meta_keywords: - - '' - meta_description: '' - image_url: '' - search_keywords: '' - custom_url: - url: /brands/Sagaform.html - is_customized: false - - id: 36 - name: OFS - page_title: OFS - meta_keywords: - - modern - - ' clean' - - ' contemporary' - meta_description: OFS is a modern brand. - image_url: '' - search_keywords: 'kitchen, laundry, cart, storage' - custom_url: - url: /brands/OFS.html - is_customized: false - - id: 37 - name: Common Good - page_title: '' - meta_keywords: - - '' - meta_description: '' - image_url: 'https://cdn8.bigcommerce.com/s-jrah6gmn/product_images/k/screen%20shot%202018-05-07%20at%2012.24.24%20pm_1525785365__65102.png' - search_keywords: '' - custom_url: - url: /brands/Common-Good.html - is_customized: false - - id: 38 - name: BigCommerce - page_title: '' - meta_keywords: - - '' - meta_description: '' - image_url: '' - search_keywords: '' - custom_url: - url: /bigcommerce/ - is_customized: false - - id: 39 - name: Test Brand One - page_title: '' - meta_keywords: - - '' - meta_description: '' - image_url: 'https://cdn8.bigcommerce.com/s-jrah6gmn/product_images/q/apihqggzm__53766.jpg' - search_keywords: '' - custom_url: - url: /test-brand-one/ - is_customized: false - - id: 40 - name: Fog Linen Work - page_title: '' - meta_keywords: - - '' - meta_description: description - image_url: '' - search_keywords: '' - custom_url: - url: /fog-linen-work/ - is_customized: false - - id: 41 - name: Barr-Co. - page_title: '' - meta_keywords: - - '' - meta_description: description - image_url: '' - search_keywords: '' - custom_url: - url: /barr-co/ - is_customized: false - - id: 42 - name: Thames & Hudson - page_title: '' - meta_keywords: - - '' - meta_description: description - image_url: '' - search_keywords: '' - custom_url: - url: /thames-hudson/ - is_customized: false - - id: 43 - name: Able Brewing - page_title: '' - meta_keywords: - - '' - meta_description: description - image_url: '' - search_keywords: '' - custom_url: - url: /able-brewing/ - is_customized: false - - id: 44 - name: Chemex - page_title: '' - meta_keywords: - - '' - meta_description: description - image_url: '' - search_keywords: '' - custom_url: - url: /chemex/ - is_customized: false - - id: 45 - name: Kinfolk - page_title: '' - meta_keywords: - - '' - meta_description: description - image_url: '' - search_keywords: '' - custom_url: - url: /kinfolk/ - is_customized: false - - id: 46 - name: Iris Hantverk - page_title: '' - meta_keywords: - - '' - meta_description: description - image_url: '' - search_keywords: '' - custom_url: - url: /iris-hantverk/ - is_customized: false - - id: 47 - name: Gather Journal - page_title: '' - meta_keywords: - - '' - meta_description: description - image_url: '' - search_keywords: '' - custom_url: - url: /gather-journal/ - is_customized: false - - id: 48 - name: Openhouse Magazine - page_title: '' - meta_keywords: - - '' - meta_description: description - image_url: '' - search_keywords: '' - custom_url: - url: /openhouse-magazine/ - is_customized: false - - id: 49 - name: Smith Journal - page_title: '' - meta_keywords: - - '' - meta_description: description - image_url: '' - search_keywords: '' - custom_url: - url: /smith-journal/ - is_customized: false - meta: - pagination: - total: 15 - count: 15 - per_page: 50 - current_page: 1 - total_pages: 1 - links: - current: '?page=1&limit=50' - post: - tags: - - Brands - summary: Create a Brand - description: |- - Creates a *Brand*. - - **Required Fields** - - name - - **Read-Only Fields** - - id - - **Limits** - - 30,000 brands per store limit - operationId: createBrand - parameters: - - $ref: '#/components/parameters/ContentType' - requestBody: - content: - application/json: - schema: - title: Brand - type: object - description: Common brand properties. - properties: - name: - maxLength: 255 - minLength: 1 - type: string - description: |- - The name of the brand. Must be unique. - Required in POST. - example: Common Good - x-required: - - post - - put - page_title: - maxLength: 255 - minLength: 0 - type: string - description: | - The title shown in the browser while viewing the brand. - example: Common Good - meta_keywords: - type: array - description: | - Comma-separated list of meta keywords to include in the HTML. - items: - type: string - example: 'modern, clean, contemporary' - meta_description: - maxLength: 65535 - minLength: 0 - type: string - description: | - A meta description to include. - example: Common Good is a modern brand. - search_keywords: - maxLength: 65535 - minLength: 0 - type: string - description: | - A comma-separated list of keywords that can be used to locate this brand. - example: 'kitchen, laundry, cart, storage' - image_url: - type: string - description: | - Image URL used for this category on the storefront. Images can be uploaded via form file post to `/brands/{brandId}/image`, or by providing a publicly accessible URL in this field. - example: 'https://cdn8.bigcommerce.com/s-12345/product_images/k/your-image-name.png' - x-url: true - custom_url: - title: Custom Url Brand - type: object - description: The custom URL for the brand on the storefront. - properties: - url: - type: string - description: | - Brand URL on the storefront. - example: /shoes - x-url: true - is_customized: - type: boolean - description: | - Returns `true` if the URL has been changed from its default state (the auto-assigned URL that BigCommerce provides). - example: true - required: - - name - required: true - responses: - '200': - description: '' - content: - application/json: - schema: - title: Brand Response - type: object - properties: - data: - title: Brand - type: object - properties: - id: - type: integer - description: Unique ID of the *Brand*. Read-Only. - readOnly: true - name: - maxLength: 255 - minLength: 1 - type: string - description: |- - The name of the brand. Must be unique. - Required in POST. - example: Common Good - x-required: - - post - - put - page_title: - maxLength: 255 - minLength: 0 - type: string - description: | - The title shown in the browser while viewing the brand. - example: Common Good - meta_keywords: - type: array - description: | - Comma-separated list of meta keywords to include in the HTML. - items: - type: string - example: 'modern, clean, contemporary' - meta_description: - maxLength: 65535 - minLength: 0 - type: string - description: | - A meta description to include. - example: Common Good is a modern brand. - search_keywords: - maxLength: 65535 - minLength: 0 - type: string - description: | - A comma-separated list of keywords that can be used to locate this brand. - example: 'kitchen, laundry, cart, storage' - image_url: - type: string - description: | - Image URL used for this category on the storefront. Images can be uploaded via form file post to `/brands/{brandId}/image`, or by providing a publicly accessible URL in this field. - example: 'https://cdn8.bigcommerce.com/s-12345/product_images/k/your-image-name.png' - x-url: true - custom_url: - title: Custom Url Brand - type: object - properties: - url: - type: string - description: | - Brand URL on the storefront. - example: /shoes - x-url: true - is_customized: - type: boolean - description: | - Returns `true` if the URL has been changed from its default state (the auto-assigned URL that BigCommerce provides). - example: true - description: The custom URL for the brand on the storefront. - description: Common Brand properties. - meta: - $ref: '#/components/schemas/metaEmpty_Full' - description: |- - Brand Response returns for: - * Create Brand - * Get Brand by Id - * Update Brand by Id - example: - data: - id: 50 - name: Common Good - meta_keywords: - - 'modern, clean, contemporary' - meta_description: Common Good is a modern brand - image_url: '' - search_keywords: 'kitchen, laundry, cart, storage' - custom_url: - url: /brands/Common-Good.html - is_customized: false - meta: {} - '207': - $ref: '#/components/responses/General207Status' - '409': - description: Brand was in conflict with another brand. This is the result of duplicate unique fields such as name. - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - '422': - description: 'Brand was not valid. This is the result of missing required fields, or of invalid data. See the response for more details.' - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - x-codegen-request-body-name: Brand - delete: - tags: - - Brands - summary: Delete Brands - description: 'By default, it deletes all *Brand* objects. A filter should be added to avoid deleting all *Brand* objects in a store.' - operationId: deleteBrands - parameters: - - name: name - in: query - description: | - Filter items by name. - schema: - type: string - - name: page_title - in: query - description: | - Filter items by page_title. - schema: - type: string - responses: - '204': - description: '' - content: {} - parameters: - - $ref: '#/components/parameters/Accept' - '/catalog/brands/{brand_id}': - get: - tags: - - Brands - summary: Get a Brand - description: Returns a single *Brand*. Optional filter parameters can be passed in. - operationId: getBrandById - parameters: - - name: brand_id - in: path - description: | - The ID of the `Brand` to which the resource belongs. - required: true - schema: - type: integer - - - name: include_fields - in: query - description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' - schema: - type: string - - name: exclude_fields - in: query - description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' - schema: - type: string - responses: - '200': - description: '' - content: - application/json: - schema: - title: Brand Response - type: object - properties: - data: - $ref: '#/components/schemas/brand_Full' - meta: - $ref: '#/components/schemas/metaEmpty_Full' - description: |- - Brand Response returns for: - * Create Brand - * Get Brand by Id - * Update Brand by Id - example: - data: - id: 50 - name: Common Good - meta_keywords: - - 'modern, clean, contemporary' - meta_description: Common Good is a modern brand - image_url: '' - search_keywords: 'kitchen, laundry, cart, storage' - custom_url: - url: /brands/Common-Good.html - is_customized: false - meta: {} - '404': - description: | - The resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - put: - tags: - - Brands - summary: Update a Brand - description: |- - Updates a *Brand*. - - **Required Fields** - - None - - **Read-Only Fields** - - id - - To update a *Brand Image*, send a request with an `image_url`. - operationId: updateBrand - parameters: - - $ref: '#/components/parameters/ContentType' - - name: brand_id - in: path - description: | - The ID of the `Brand` to which the resource belongs. - required: true - schema: - type: integer - requestBody: - content: - application/json: - schema: - title: Brand - required: - - name - type: object - properties: - id: - type: integer - description: Unique ID of the *Brand*. Read-Only. - readOnly: true - name: - maxLength: 255 - minLength: 1 - type: string - description: |- - The name of the brand. Must be unique. - Required in POST. - example: Common Good - x-required: - - post - - put - page_title: - maxLength: 255 - minLength: 0 - type: string - description: | - The title shown in the browser while viewing the brand. - example: Common Good - meta_keywords: - type: array - description: | - Comma-separated list of meta keywords to include in the HTML. - example: - - 'modern, clean, contemporary' - items: - type: string - meta_description: - maxLength: 65535 - minLength: 0 - type: string - description: | - A meta description to include. - example: Common Good is a modern brand. - search_keywords: - maxLength: 65535 - minLength: 0 - type: string - description: | - A comma-separated list of keywords that can be used to locate this brand. - example: 'kitchen, laundry, cart, storage' - image_url: - type: string - description: | - Image URL used for this category on the storefront. Images can be uploaded via form file post to `/brands/{brandId}/image`, or by providing a publicly accessible URL in this field. - example: 'https://cdn8.bigcommerce.com/s-12345/product_images/k/your-image-name.png' - x-url: true - custom_url: - title: Custom Url Brand - type: object - properties: - url: - type: string - description: | - Brand URL on the storefront. - example: /shoes - x-url: true - is_customized: - type: boolean - description: | - Returns `true` if the URL has been changed from its default state (the auto-assigned URL that BigCommerce provides). - example: true - description: The custom URL for the brand on the storefront. - description: Common Brand properties. - required: true - responses: - '200': - description: '' - content: - application/json: - schema: - title: Brand Response - type: object - properties: - data: - title: Brand - required: - - name - type: object - properties: - id: - type: integer - description: Unique ID of the *Brand*. Read-Only. - readOnly: true - name: - maxLength: 255 - minLength: 1 - type: string - description: |- - The name of the brand. Must be unique. - Required in POST. - example: Common Good - x-required: - - post - - put - page_title: - maxLength: 255 - minLength: 0 - type: string - description: | - The title shown in the browser while viewing the brand. - example: Common Good - meta_keywords: - type: array - description: | - Comma-separated list of meta keywords to include in the HTML. - example: - - 'modern, clean, contemporary' - items: - type: string - meta_description: - maxLength: 65535 - minLength: 0 - type: string - description: | - A meta description to include. - example: Common Good is a modern brand. - search_keywords: - maxLength: 65535 - minLength: 0 - type: string - description: | - A comma-separated list of keywords that can be used to locate this brand. - example: 'kitchen, laundry, cart, storage' - image_url: - type: string - description: | - Image URL used for this category on the storefront. Images can be uploaded via form file post to `/brands/{brandId}/image`, or by providing a publicly accessible URL in this field. - example: 'https://cdn8.bigcommerce.com/s-12345/product_images/k/your-image-name.png' - x-url: true - custom_url: - title: Custom Url Brand - type: object - properties: - url: - type: string - description: | - Brand URL on the storefront. - example: /shoes - x-url: true - is_customized: - type: boolean - description: | - Returns `true` if the URL has been changed from its default state (the auto-assigned URL that BigCommerce provides). - example: true - description: The custom URL for the brand on the storefront. - description: Common Brand properties. - meta: - $ref: '#/components/schemas/metaEmpty_Full' - description: |- - Brand Response returns for: - * Create Brand - * Get Brand by Id - * Update Brand by Id - example: - data: - id: 50 - name: Common Good - meta_keywords: - - 'modern, clean, contemporary' - meta_description: Common Good is a modern brand - image_url: '' - search_keywords: 'kitchen, laundry, cart, storage' - custom_url: - url: /brands/Common-Good.html - is_customized: false - meta: {} - '207': - $ref: '#/components/responses/General207Status' - '404': - description: | - The resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - '409': - description: | - The `Brand` was in conflict with another product. This is the result of duplicate unique values, such as `name`. - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - '422': - description: | - The `Brand` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - x-codegen-request-body-name: brand - delete: - tags: - - Brands - summary: Delete a Brand - description: Deletes a *Brand*. - operationId: deleteBrandById - parameters: - - name: brand_id - in: path - description: | - The ID of the `Brand` to which the resource belongs. - required: true - schema: - type: integer - responses: - '204': - description: '' - content: {} - parameters: - - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/BrandIdParam' - '/catalog/brands/{brand_id}/metafields': - get: - tags: - - Brand Metafields - summary: Get All Brand Metafields - description: 'Returns a list of *Brand Metafields*. Optional filter parameters can be passed in. ' - operationId: getBrandMetafieldsByBrandId - parameters: - - name: brand_id - in: path - description: | - The ID of the `Brand` to which the resource belongs. - required: true - schema: - type: integer - - - name: id - in: query - description: | - Filter items by id. - schema: - type: integer - - name: 'id:in' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: 'id:not_in' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: 'id:min' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: 'id:max' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: 'id:greater' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: 'id:less' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - - name: page - in: query - description: Specifies the page number in a limited (paginated) list of products. - schema: - type: integer - - name: limit - in: query - description: Controls the number of items per page in a limited (paginated) list of products. - schema: - type: integer - - name: key - in: query - description: | - Filter based on a metafield's key. - schema: - type: string - - name: namespace - in: query - description: Filter based on a metafield's namespace. - schema: - type: string - - name: include_fields - in: query - description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' - schema: - type: string - - name: exclude_fields - in: query - description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' - schema: - type: string - responses: - '200': - description: '' - content: - application/json: - schema: - title: Meta Field Collection Response - type: object - properties: - data: - type: array - items: - $ref: '#/components/schemas/metafield_Full' - meta: - $ref: '#/components/schemas/metaCollection_Full' - example: - data: - - id: 6 - key: Location - value: 4HG - namespace: Warehouse Locations - permission_set: app_only - resource_type: brand - resource_id: 111 - description: Location in the warehouse - date_created: '1973-01-20T21:34:57.903Z' - date_modified: '1990-12-30T00:29:23.515Z' - - id: 7 - key: Brand location - value: 4HG - namespace: Warehouse Locations - permission_set: read - resource_type: brand - resource_id: 111 - description: Location in the warehouse - date_created: '1973-01-20T21:34:57.903Z' - date_modified: '1990-12-30T00:29:23.515Z' - meta: - pagination: - total: 2 - count: 2 - per_page: 50 - current_page: 1 - total_pages: 1 - links: - current: '?page=1&limit=50' - '404': - description: | - The resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - post: - tags: - - Brand Metafields - summary: Create a Brand Metafield - description: |- - Creates a *Brand Metafield*. - - **Required Fields** - - permission_set - - namespace - - key - - value - - **Read-Only Fields** - - id - - **Note:** The maxiumum number of metafields allowed on each order, product, category, variant, or brand is 250 per client ID. For more information, see [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center. - operationId: createBrandMetafield - parameters: - - $ref: '#/components/parameters/ContentType' - - name: brand_id - in: path - description: | - The ID of the `Brand` to which the resource belongs. - required: true - schema: - type: integer - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/metafield_Base' - required: true - responses: - '200': - description: '' - content: - application/json: - schema: - title: Metafield Response - type: object - properties: - data: - $ref: '#/components/schemas/metafield_Full' - meta: - title: Meta - type: object - properties: {} - description: Empty meta object; may be used later. - example: - data: - id: 4 - key: location_id - value: 'Shelf 3, Bin 5' - namespace: App Namespace - permission_set: app_only - resource_type: brand - resource_id: 137 - description: Where products are located - date_created: '2021-08-06T19:15:35+00:00' - date_modified: '2021-08-06T19:15:35+00:00' - meta: {} - examples: - example-1: - value: - data: - id: 6 - key: Location - value: 4HG - namespace: Warehouse Locations - permission_set: app_only - resource_type: category - resource_id: 111 - description: Location in the warehouse - date_created: '2018-05-07T20:14:17+00:00' - date_modified: '2018-05-07T20:14:17+00:00' - meta: {} - example-2: - value: - data: - id: 4 - key: location_id - value: 'Shelf 3, Bin 5' - namespace: App Namespace - permission_set: app_only - resource_type: brand - resource_id: 137 - description: Where products are located - date_created: '2021-08-06T19:15:35+00:00' - date_modified: '2021-08-06T19:15:35+00:00' - meta: {} - '409': - description: | - The `Metafield` was in conflict with another `Metafield`. This can be the result of duplicate unique key combination of the app's client id, namespace, key, resource_type, and resource_id. - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - '422': - description: | - The `Metafield` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - x-codegen-request-body-name: Metafield - parameters: - - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/BrandIdParam' - '/catalog/brands/{brand_id}/metafields/{metafield_id}': - get: - tags: - - Brand Metafields - summary: Get a Brand Metafields - description: Returns a *Brand Metafield*. Optional filter parameters can be passed in. - operationId: getBrandMetafieldByBrandId - parameters: - - name: metafield_id - in: path - description: | - The ID of the `Metafield`. - required: true - schema: - type: integer - - name: brand_id - in: path - description: | - The ID of the `Brand` to which the resource belongs. - required: true - schema: - type: integer - - - name: include_fields - in: query - description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' - schema: - type: string - - name: exclude_fields - in: query - description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' - schema: - type: string - responses: - '200': - description: '' - content: - application/json: - schema: - title: Metafield Response - type: object - properties: - data: - $ref: '#/components/schemas/metafield_Full' - meta: - $ref: '#/components/schemas/metaEmpty_Full' - example: - data: - id: 4 - key: location_id - value: 'Shelf 3, Bin 5' - namespace: App Namespace - permission_set: app_only - resource_type: product - resource_id: 137 - description: Where products are located - date_created: '2021-08-06T19:15:35+00:00' - date_modified: '2021-08-06T19:15:35+00:00' - meta: {} - '404': - description: | - The resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - put: - tags: - - Brand Metafields - summary: Update a Brand Metafield - description: "Updates a *Brand Metafield*.\n\n**Required Fields** \n* none\n\n**Read-Only Fields**\n* id\n* These fields can only be modified by the app (API credentials) that created the metafield:\n\t* namespace\n\t* key\n\t* permission_set\n\n**Usage Notes**\n* Attempting to modify `namespace`, `key`, and `permission_set` fields using a client ID different from the one used to create those metafields will result in a 403 error message.\n* The maxiumum number of metafields allowed on each order, product, category, variant, or brand is 250 per client ID. For more information, see [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center." - operationId: updateBrandMetafield - parameters: - - $ref: '#/components/parameters/ContentType' - - name: metafield_id - in: path - description: | - The ID of the `Metafield`. - required: true - schema: - type: integer - - name: brand_id - in: path - description: | - The ID of the `Brand` to which the resource belongs. - required: true - schema: - type: integer - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/metafield_Base' - required: true - responses: - '200': - description: '' - content: - application/json: - schema: - title: Metafield Response - type: object - properties: - data: - $ref: '#/components/schemas/metafield_Full' - meta: - $ref: '#/components/schemas/metaEmpty_Full' - example: - data: - id: 4 - key: location_id - value: 'Shelf 3, Bin 5' - namespace: App Namespace - permission_set: app_only - resource_type: product - resource_id: 137 - description: Where products are located - date_created: '2021-08-06T19:15:35+00:00' - date_modified: '2021-08-06T19:15:35+00:00' - meta: {} - '404': - description: | - The resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - x-codegen-request-body-name: Metafield - delete: - tags: - - Brand Metafields - summary: Delete a Brand Metafield - description: Deletes a *Brand Metafield*. - operationId: deleteBrandMetafieldById - parameters: - - name: metafield_id - in: path - description: | - The ID of the `Metafield`. - required: true - schema: - type: integer - - name: brand_id - in: path - description: | - The ID of the `Brand` to which the resource belongs. - required: true - schema: - type: integer - responses: - '204': - description: '' - content: {} - parameters: - - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/BrandIdParam' - - $ref: '#/components/parameters/MetafieldIdParam' - '/catalog/brands/{brand_id}/image': - post: - tags: - - Brand Images - summary: Create a Brand Image - description: |- - Creates a *Brand Image*. - - **Required Fields** - - image_file: Form posts are the only accepted upload option. - - **Read-Only Fields** - - id - - Only one image at a time can be created. To update a *Brand Image*, use the [Update a brand](/docs/rest-management/catalog/brands#update-a-brand) endpoint and an `image_url`. - operationId: createBrandImage - parameters: - - $ref: '#/components/parameters/ContentType' - - name: brand_id - in: path - description: | - The ID of the `Brand` to which the resource belongs. - required: true - schema: - type: integer - requestBody: - content: - multipart/form-data: - schema: - type: object - properties: - image_file: - type: string - format: binary - responses: - '200': - description: '' - content: - application/json: - schema: - type: object - properties: - data: - type: object - properties: - image_url: - type: string - meta: - $ref: '#/components/schemas/metaEmpty_Full' - example: - data: - image_url: 'https://cdn11.bigcommerce.com/s-{store_hash}/product_images/k/group_1545334669__76009.png' - meta: {} - '400': - description: Bad Request. The requested resource could not be downloaded and may be invalid. Possible reasons include malformed request syntax or the file host blocking requests. - content: - application/json: - schema: - type: object - properties: {} - '404': - description: The resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - '422': - description: 'Image was not valid. This is the result of a missing `image_file` field, or of an incorrect file type. See the response for more details.' - content: - application/json: - schema: - title: Error Response - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - instance: - type: string - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - delete: - tags: - - Brand Images - summary: Delete a Brand Image - description: Deletes a *Brand Image*. - operationId: deleteBrandImage - parameters: - - name: brand_id - in: path - description: | - The ID of the `Brand` to which the resource belongs. - required: true - schema: - type: integer - responses: - '204': - description: '' - content: {} - parameters: - - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/BrandIdParam' - '/catalog/variants': - get: - tags: - - Variants - summary: Get All Variants - description: Returns a list of all variants in your catalog. Optional parameters can be passed in. - operationId: getVariants - parameters: - - name: id - in: query - description: | - Filter items by id. - schema: - type: integer - - name: sku - in: query - description: | - Filter items by sku. - schema: - type: string - - name: page - in: query - description: Specifies the page number in a limited (paginated) list of products. - schema: - type: integer - - name: limit - in: query - description: Controls the number of items per page in a limited (paginated) list of products. - schema: - type: integer - - name: include_fields - in: query - description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' - schema: - type: string - - name: exclude_fields - in: query - description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' - schema: - type: string - - name: product_id - in: query - description: 'A comma-separated list of IDs of products whose variants were requested. For example:`?product_id=:id``?product_id:in=77,80,81`' - schema: - type: string - responses: - '200': - description: '' - content: - application/json: - schema: - title: Variant Collection Response - type: object - properties: - data: - type: array - items: - type: object - allOf: - - title: Variant Base - type: object - properties: - cost_price: - minimum: 0 - type: number - description: The cost price of the variant. Not affected by Price List prices. - format: double - x-nullable: true - price: - minimum: 0 - type: number - description: 'This variant’s base price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is `null`, the product’s default price (set in the Product resource’s `price` field) will be used as the base price.' - format: double - x-nullable: true - sale_price: - minimum: 0 - type: number - description: 'This variant’s sale price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s sale price (set in the Product resource’s `price` field) will be used as the sale price.' - format: double - x-nullable: true - retail_price: - minimum: 0 - type: number - description: 'This variant’s retail price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s retail price (set in the Product resource’s `price` field) will be used as the retail price.' - format: double - x-nullable: true - weight: - minimum: 0 - type: number - description: 'This variant’s base weight on the storefront. If this value is null, the product’s default weight (set in the Product resource’s weight field) will be used as the base weight.' - format: double - x-nullable: true - width: - minimum: 0 - type: number - description: | - Width of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default width (set in the Product resource's `width` field) will be used as the base width. - format: double - x-nullable: true - height: - minimum: 0 - type: number - description: | - Height of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default height (set in the Product resource's `height` field) will be used as the base height. - format: double - x-nullable: true - depth: - minimum: 0 - type: number - description: | - Depth of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default depth (set in the Product resource's `depth` field) will be used as the base depth. - format: double - x-nullable: true - is_free_shipping: - type: boolean - description: | - Flag used to indicate whether the variant has free shipping. If `true`, the shipping cost for the variant will be zero. - fixed_cost_shipping_price: - minimum: 0 - type: number - description: | - A fixed shipping cost for the variant. If defined, this value will be used during checkout instead of normal shipping-cost calculation. - format: double - x-nullable: true - purchasing_disabled: - type: boolean - description: 'If `true`, this variant will not be purchasable on the storefront.' - purchasing_disabled_message: - maxLength: 255 - minLength: 0 - type: string - description: 'If `purchasing_disabled` is `true`, this message should show on the storefront when the variant is selected.' - upc: - type: string - description: The UPC code used in feeds for shopping comparison sites and external channel integrations. - x-nullable: true - inventory_level: - type: integer - description: 'Inventory level for the variant, which is used when the product’s inventory_tracking is set to `variant`.' - x-nullable: true - inventory_warning_level: - type: integer - description: 'When the variant hits this inventory level, it is considered low stock.' - x-nullable: true - bin_picking_number: - maxLength: 255 - minLength: 0 - type: string - description: Identifies where in a warehouse the variant is located. - x-nullable: true - description: Common Variant properties. - - type: object - properties: - id: - type: integer - product_id: - type: integer - sku: - type: string - sku_id: - type: integer - description: Read-only reference to v2 API's SKU ID. Null if it is a base variant. - x-nullable: true - option_values: - type: array - description: Array of option and option values IDs that make up this variant. Will be empty if the variant is the product's base variant. - items: - title: Option Value Variant - type: object - allOf: - - title: Option Value Product Base - type: object - properties: - option_display_name: - maxLength: 255 - minLength: 1 - type: string - description: | - The name of the option. - example: Color - x-required: - - post - label: - maxLength: 255 - minLength: 1 - type: string - description: | - The label of the option value. - example: Beige - x-required: - - post - description: Common Option Value Product properties. - - type: object - properties: - id: - type: integer - option_id: - type: integer - calculated_price: - type: number - description: | - The price of the variant as seen on the storefront. This price takes into account `sale_price` and any price adjustment rules that are applicable to this variant. - format: double - meta: - $ref: '#/components/schemas/metaCollection_Full' - '404': - description: The resource was not found. - content: - application/json: - schema: - title: Not Found - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - put: - tags: - - Variants - summary: Update Variants (Batch) - description: 'Updates a batch of `variant` objects. At the time of writing, the limit is 50 variants. This limit is subject to change.' - operationId: updateVariantsBatch - parameters: - - $ref: '#/components/parameters/ContentType' - requestBody: - content: - application/json: - schema: - title: Variants Collection Put - type: array - items: - title: Variant Put - type: object - description: | - The model for a PUT to update variants on a product. - allOf: - - title: Variant Base - type: object - properties: - cost_price: - minimum: 0 - type: number - description: The cost price of the variant. Not affected by Price List prices. - format: double - x-nullable: true - price: - minimum: 0 - type: number - description: 'This variant’s base price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is `null`, the product’s default price (set in the Product resource’s `price` field) will be used as the base price.' - format: double - x-nullable: true - sale_price: - minimum: 0 - type: number - description: 'This variant’s sale price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s sale price (set in the Product resource’s `price` field) will be used as the sale price.' - format: double - x-nullable: true - retail_price: - minimum: 0 - type: number - description: 'This variant’s retail price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s retail price (set in the Product resource’s `price` field) will be used as the retail price.' - format: double - x-nullable: true - weight: - minimum: 0 - type: number - description: 'This variant’s base weight on the storefront. If this value is null, the product’s default weight (set in the Product resource’s weight field) will be used as the base weight.' - format: double - x-nullable: true - width: - minimum: 0 - type: number - description: | - Width of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default width (set in the Product resource's `width` field) will be used as the base width. - format: double - x-nullable: true - height: - minimum: 0 - type: number - description: | - Height of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default height (set in the Product resource's `height` field) will be used as the base height. - format: double - x-nullable: true - depth: - minimum: 0 - type: number - description: | - Depth of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default depth (set in the Product resource's `depth` field) will be used as the base depth. - format: double - x-nullable: true - is_free_shipping: - type: boolean - description: | - Flag used to indicate whether the variant has free shipping. If `true`, the shipping cost for the variant will be zero. - fixed_cost_shipping_price: - minimum: 0 - type: number - description: | - A fixed shipping cost for the variant. If defined, this value will be used during checkout instead of normal shipping-cost calculation. - format: double - x-nullable: true - purchasing_disabled: - type: boolean - description: 'If `true`, this variant will not be purchasable on the storefront.' - purchasing_disabled_message: - maxLength: 255 - minLength: 0 - type: string - description: 'If `purchasing_disabled` is `true`, this message should show on the storefront when the variant is selected.' - upc: - type: string - description: The UPC code used in feeds for shopping comparison sites and external channel integrations. - x-nullable: true - inventory_level: - type: integer - description: 'Inventory level for the variant, which is used when the product’s inventory_tracking is set to `variant`.' - x-nullable: true - inventory_warning_level: - type: integer - description: 'When the variant hits this inventory level, it is considered low stock.' - x-nullable: true - bin_picking_number: - maxLength: 255 - minLength: 0 - type: string - description: Identifies where in a warehouse the variant is located. - x-nullable: true - description: Common Variant properties. - - type: object - properties: - id: - type: integer - x-required: - - put - required: true - responses: - '200': - description: '' - content: - application/json: - schema: - title: Variant Collection Response - type: object - properties: - data: - type: array - items: - type: object - allOf: - - title: Variant Base - type: object - properties: - cost_price: - minimum: 0 - type: number - description: The cost price of the variant. Not affected by Price List prices. - format: double - x-nullable: true - price: - minimum: 0 - type: number - description: 'This variant’s base price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is `null`, the product’s default price (set in the Product resource’s `price` field) will be used as the base price.' - format: double - x-nullable: true - sale_price: - minimum: 0 - type: number - description: 'This variant’s sale price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s sale price (set in the Product resource’s `price` field) will be used as the sale price.' - format: double - x-nullable: true - retail_price: - minimum: 0 - type: number - description: 'This variant’s retail price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s retail price (set in the Product resource’s `price` field) will be used as the retail price.' - format: double - x-nullable: true - weight: - minimum: 0 - type: number - description: 'This variant’s base weight on the storefront. If this value is null, the product’s default weight (set in the Product resource’s weight field) will be used as the base weight.' - format: double - x-nullable: true - width: - minimum: 0 - type: number - description: | - Width of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default width (set in the Product resource's `width` field) will be used as the base width. - format: double - x-nullable: true - height: - minimum: 0 - type: number - description: | - Height of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default height (set in the Product resource's `height` field) will be used as the base height. - format: double - x-nullable: true - depth: - minimum: 0 - type: number - description: | - Depth of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default depth (set in the Product resource's `depth` field) will be used as the base depth. - format: double - x-nullable: true - is_free_shipping: - type: boolean - description: | - Flag used to indicate whether the variant has free shipping. If `true`, the shipping cost for the variant will be zero. - fixed_cost_shipping_price: - minimum: 0 - type: number - description: | - A fixed shipping cost for the variant. If defined, this value will be used during checkout instead of normal shipping-cost calculation. - format: double - x-nullable: true - purchasing_disabled: - type: boolean - description: 'If `true`, this variant will not be purchasable on the storefront.' - purchasing_disabled_message: - maxLength: 255 - minLength: 0 - type: string - description: 'If `purchasing_disabled` is `true`, this message should show on the storefront when the variant is selected.' - upc: - type: string - description: The UPC code used in feeds for shopping comparison sites and external channel integrations. - x-nullable: true - inventory_level: - type: integer - description: 'Inventory level for the variant, which is used when the product’s inventory_tracking is set to `variant`.' - x-nullable: true - inventory_warning_level: - type: integer - description: 'When the variant hits this inventory level, it is considered low stock.' - x-nullable: true - bin_picking_number: - maxLength: 255 - minLength: 0 - type: string - description: Identifies where in a warehouse the variant is located. - x-nullable: true - description: Common Variant properties. - - type: object - properties: - id: - type: integer - product_id: - type: integer - sku: - type: string - sku_id: - type: integer - description: Read-only reference to v2 API's SKU ID. Null if it is a base variant. - x-nullable: true - option_values: - type: array - description: Array of option and option values IDs that make up this variant. Will be empty if the variant is the product's base variant. - items: - title: Option Value Variant - type: object - allOf: - - title: Option Value Product Base - type: object - properties: - option_display_name: - maxLength: 255 - minLength: 1 - type: string - description: | - The name of the option. - example: Color - x-required: - - post - label: - maxLength: 255 - minLength: 1 - type: string - description: | - The label of the option value. - example: Beige - x-required: - - post - description: Common Option Value Product properties. - - type: object - properties: - id: - type: integer - option_id: - type: integer - calculated_price: - type: number - description: | - The price of the variant as seen on the storefront. This price takes into account `sale_price` and any price adjustment rules that are applicable to this variant. - format: double - meta: - title: Collection Meta - type: object - properties: - pagination: - title: Pagination - type: object - properties: - total: - type: integer - description: | - Total number of items in the result set. - example: 36 - count: - type: integer - description: | - Total number of items in the collection response. - example: 36 - per_page: - type: integer - description: | - The amount of items returned in the collection per page, controlled by the limit parameter. - example: 50 - current_page: - type: integer - description: | - The page you are currently on within the collection. - example: 1 - total_pages: - type: integer - description: | - The total number of pages in the collection. - example: 1 - links: - type: object - properties: - previous: - type: string - description: | - Link to the previous page returned in the response. - current: - type: string - description: | - Link to the current page returned in the response. - example: '?page=1&limit=50' - next: - type: string - description: | - Link to the next page returned in the response. - description: | - Pagination links for the previous and next parts of the whole collection. - description: 'Data about the response, including pagination and collection totals.' - description: 'Data about the response, including pagination and collection totals.' - '413': - description: '' - content: - application/json: - example: - errors: {} - status: 413 - title: The request payload is too large. The maximum items allowed in the array is 50 - type: /api-docs/getting-started/api-status-codes - '422': - description: | - This is the result of missing required fields, or of invalid data. See the response for more details. - content: - application/json: - schema: - title: Variants Batch Error Response - type: object - properties: - batch_errors: - type: array - items: - title: Error Response - type: object - allOf: - - title: Base Error - type: object - properties: - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - instance: - type: string - description: | - Error payload for the BigCommerce API. - - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - description: | - Errors during batch usage for the BigCommerce API. - x-codegen-request-body-name: body - parameters: - - $ref: '#/components/parameters/Accept' - '/catalog/summary': - get: - tags: - - Summary - summary: Get a Catalog Summary - description: |- - Returns a lightweight inventory summary from the BigCommerce Catalog. - - The inventory summary includes: - * "inventory_count" - * "variant_count" - * "inventory_value" - * "highest_variant_price" - * "average_variant_price" - * "lowest_variant_price" - * "oldest_variant_date" - * "newest_variant_date" - * "primary_category_id" - * "primary_category_name" - operationId: getCatalogSummary - responses: - '200': - description: '' - content: - application/json: - schema: - title: Catalog Summary Response - type: object - properties: - data: - title: Catalog Summary - type: object - properties: - inventory_count: - type: integer - description: | - A count of all inventory items in the catalog. - example: 2000 - inventory_value: - type: number - description: | - Total value of store's inventory. - format: double - example: 267000 - primary_category_id: - type: integer - description: | - ID of the category containing the most products. - example: 23 - primary_category_name: - type: string - description: | - Name of the category containing the most products. - example: Shop All - variant_count: - type: integer - description: Total number of variants - example: 46 - highest_variant_price: - type: number - description: Highest priced variant - format: double - example: 249 - average_variant_price: - type: number - description: Average price of all variants - format: double - example: 83.07978261 - lowest_variant_price: - type: string - description: Lowest priced variant in the store - example: '7' - oldest_variant_date: - type: string - example: '2018-08-15T00:00:00+00:00' - newest_variant_date: - type: string - example: '2018-08-16T00:00:00+00:00' - description: Catalog Summary object describes a lightweight summary of the catalog. - meta: - $ref: '#/components/schemas/metaEmpty_Full' - parameters: - - $ref: '#/components/parameters/Accept' - '/catalog/categories/{category_id}/products/sort-order': - get: - tags: - - Product Sort Order - summary: Get Product Sort Order - description: |- - Returns a list of products and their sort order for a specific category. - - **Usage Notes** - * Data pairs are displayed in ascending order based on products' `sort_order` values. - * `null` values are allowed for products without specified `sort_order` values. - * Products with `sort_order` value of `null` will be displayed after products with valid numerical values. - * The priorities for determining product sort order on a storefront are the following: - - Priority 1: Manually specified sort order on Category Level (API). - - Priority 2: Manually specified sort order on Product (Global) Level (UI/API). - - Priority 3: Default sorting by Product ID (newly added products go first) (UI/API). - operationId: getsortorders - parameters: - - name: category_id - in: path - description: The ID of the `Category` to which the resource belongs. - required: true - schema: - type: integer - responses: - '200': - description: '' - content: - application/json: - schema: - type: object - properties: {} - '404': - description: The requested category was not found. - content: - application/json: - schema: - $ref: '#/components/schemas/error_Base' - put: - tags: - - Product Sort Order - summary: Update Product Sort Order - description: Updates sort order of products within a specific category. - operationId: updatesortorder - parameters: - - $ref: '#/components/parameters/ContentType' - - name: category_id - in: path - description: The ID of the `Category` to which the resource belongs. - required: true - schema: - type: integer - requestBody: - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/productSortOrder' - required: false - responses: - '200': - description: '' - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/productSortOrder' - '404': - description: The requested category was not found. - content: - application/json: - schema: - $ref: '#/components/schemas/error_Base' - '422': - description: |- - Unprocessable entity. - - Please verify if all requested products are assigned to the category. - - Please verify if all required fields are present in the request body and are filled with values correctly. - content: - application/json: - schema: - $ref: '#/components/schemas/error_Base' - x-codegen-request-body-name: body - parameters: - - $ref: '#/components/parameters/Accept' - - $ref: '#/components/parameters/CategoryIdParam' - '/catalog/trees/categories': - get: - summary: Get All Categories - description: |- - Returns a list of categories. - - To get a specific category in a tree, provide a category id. - tags: - - Categories Batch - parameters: - - name: 'category_uuid:in' - in: query - schema: - type: string - - name: 'category_uuid:not_in' - in: query - schema: - type: string - - name: 'category_id:in' - in: query - schema: - type: string - - name: 'category_id:not_in' - in: query - schema: - type: string - - name: 'tree_id:in' - in: query - schema: - type: string - - name: 'tree_id:not_in' - in: query - schema: - type: string - - name: 'parent_id:in' - in: query - schema: - type: string - - name: 'parent_id:not_in' - in: query - schema: - type: string - - name: name - in: query - schema: - type: string - - name: 'name:like' - in: query - schema: - type: string - - name: page_title - in: query - schema: - type: string - - name: 'page_title:like' - in: query - schema: - type: string - - name: keyword - in: query - schema: - type: string - - name: is_visible - in: query - schema: - type: boolean - - name: page - in: query - schema: - type: integer - - name: limit - in: query - schema: - type: integer - - name: include_fields - in: query - schema: - type: string - - name: exclude_fields - in: query - schema: - type: string - responses: - '200': - description: List of categories. - content: - application/json: - schema: - type: object - properties: - data: - type: array - items: - $ref: '#/components/schemas/Category' - meta: - $ref: '#/components/schemas/MetaPagination' - examples: - example-1: - value: - data: - - id: 0 - parent_id: 2 - name: Bath - description: <p>We offer a wide variety of products perfect for relaxing</p> - views: 1050 - sort_order: 3 - page_title: Bath - meta_keywords: - - string - meta_description: string - layout_file: category.html - image_url: 'https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png' - is_visible: true - search_keywords: string - default_product_sort: use_store_settings - url: - path: string - is_customized: true - meta: - pagination: - total: 246 - count: 5 - per_page: 5 - current_page: 1 - total_pages: 50 - links: - previous: '?limit=5&page=1' - current: '?limit=5&page=2' - next: '?limit=5&page=3' - '400': - description: Bad Request - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorRequest' - '500': - description: Internal Server Error - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorRequest' - operationId: getAllCategories - post: - summary: Create Categories - description: |- - Creates new categories. - - Creating a category requires: - - `name` - - `url` - - `tree_id` or `parent_id` - parameters: - - $ref: '#/components/parameters/ContentType' - tags: - - Categories Batch - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/CreateCategories' - responses: - '201': - description: Created - content: - application/json: - schema: - $ref: '#/components/schemas/SuccessResponse' - '207': - description: Multi-Status - content: - application/json: - schema: - $ref: '#/components/schemas/PartialSuccessResponse' - '400': - description: Bad Request - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorRequest' - '422': - description: 'The Category was not valid. This is the result of missing required fields, or of invalid data. See the response for more details.' - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorResponse' - '500': - description: Internal Server Error - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorRequest' - operationId: createCategories - put: - summary: Update Categories - description: |- - Updates existing categories. - - To update a specific category in a tree, provide a category id. - parameters: - - $ref: '#/components/parameters/ContentType' - tags: - - Categories Batch - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/UpdateCategories' - responses: - '200': - description: OK - '204': - description: No Content - content: - application/json: - schema: - $ref: '#/components/schemas/SuccessNoContentResponse' - '207': - description: Partial success - content: - application/json: - schema: - $ref: '#/components/schemas/PartialSuccessNoContentResponse' - '400': - description: Bad request - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorRequest' - '422': - description: 'The Category was not valid. This is the result of missing required fields, or of invalid data. See the response for more details.' - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorResponse' - '500': - description: Internal Server Error - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorRequest' - operationId: updateCategories - delete: - summary: Delete Categories - description: |- - Deletes categories. - - To delete a specific category in a tree, provide a category id. - tags: - - Categories Batch - parameters: - - name: 'category_uuid:in' - in: query - schema: - type: string - - name: 'category_id:in' - in: query - schema: - type: string - - name: 'tree_id:in' - in: query - schema: - type: string - - name: 'parent_id:in' - in: query - schema: - type: string - responses: - '204': - description: Categories are deleted - content: - application/json: - schema: - $ref: '#/components/schemas/SuccessNoContentResponse' - '400': - description: Bad request - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorRequest' - '500': - description: Server error - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorRequest' - operationId: deleteTreeCategories - parameters: - - $ref: '#/components/parameters/Accept' - '/catalog/trees': - get: - summary: Get All Category Trees - description: Returns a list of *Category Trees*. - operationId: GetCategoryTrees - parameters: - - name: 'id:in' - in: query - schema: - type: string - - name: 'channel_id:in' - in: query - schema: - type: string - responses: - '200': - description: List of category trees. - content: - application/json: - schema: - type: object - properties: - data: - type: array - items: - $ref: '#/components/schemas/Tree' - meta: - $ref: '#/components/schemas/MetaPaginationObject' - example: - data: - - id: 0 - name: string - channels: - - 0 - meta: - pagination: - total: 246 - count: 5 - per_page: 5 - current_page: 1 - total_pages: 50 - links: - next: '?limit=5&page=2' - current: '?limit=5&page=1' - tags: - - Category Trees - put: - summary: Upsert Category Trees - description: | - Upserts *Category Trees*. - - If a tree object contains an ID, it is processed as an update operation using that ID. If no ID is provided, a new tree is created. - - **Usage Notes** - * `channel_id` is required to create a *Category Tree*. - parameters: - - $ref: '#/components/parameters/ContentType' - operationId: UpsertCategoryTrees - requestBody: - required: true - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/Tree' - example: - - id: 0 - name: string - channels: - - 0 - responses: - '200': - description: Created a category tree. - content: - application/json: - schema: - type: object - properties: - data: - $ref: '#/components/schemas/Tree' - meta: - $ref: '#/components/schemas/metaEmpty_Full' - example: - data: - id: 0 - name: string - channels: - - 0 - meta: - type: object - properties: {} - description: Empty meta object; reserved for use later. - '422': - description: The Channel was not valid. See the response for more details. - content: - application/json: - schema: - $ref: '#/components/schemas/beta4ErrorResponse' - example: - status: 0 - title: string - type: string - instance: string - errors: - additionalProp1: string - additionalProp2: string - additionalProp3: string - tags: - - Category Trees - delete: - summary: Delete Category Trees - description: Deletes *Category Trees*. A filter must be supplied with the endpoint. - operationId: DeleteCategoryTrees - parameters: - - name: 'id:in' - in: query - schema: - type: string - responses: - '204': - description: Deleted - tags: - - Category Trees - parameters: - - $ref: '#/components/parameters/Accept' - '/catalog/trees/{tree_id}/categories': - get: - summary: Get a Category Tree - description: Returns a *Category Tree*. - operationId: GetCategoryTreeByTreeId - parameters: - - name: depth - description: Max depth for a tree of categories. - in: query - schema: - type: integer - responses: - '200': - description: Categories tree - content: - application/json: - schema: - type: object - properties: - data: - type: array - items: - $ref: '#/components/schemas/CategoryNode' - meta: - $ref: '#/components/schemas/metaEmpty_Full' - example: - data: - - id: 0 - parent_id: 0 - depth: 0 - path: - - 0 - name: string - is_visible: true - children: - - string - meta: - type: object - properties: {} - description: Empty meta object; reserved for use later. - '404': - description: The tree was not found. - content: - application/json: - schema: - $ref: '#/components/schemas/beta4ErrorResponse' - example: - status: 0 - title: string - type: string - instance: string - errors: - additionalProp1: string - additionalProp2: string - additionalProp3: string - tags: - - Category Trees - parameters: - - $ref: '#/components/parameters/Accept' - - schema: - type: string - name: tree_id - in: path - required: true - '/catalog/products/channel-assignments': - get: - summary: Get Products Channel Assignments - description: Returns a list of products channel assignments. - operationId: GetProductsChannelAssignments - tags: - - Products Channel Assignments - parameters: - - name: page - in: query - schema: - type: integer - - name: limit - in: query - schema: - type: integer - - name: 'product_id:in' - in: query - schema: - type: string - - name: 'channel_id:in' - in: query - schema: - type: string - responses: - '200': - description: Collection of channel assignments. - content: - application/json: - schema: - type: object - properties: - data: - type: array - items: - $ref: '#/components/schemas/ProductChannelAssignment' - meta: - $ref: '#/components/schemas/MetaPaginationObject' - put: - summary: Create Products Channel Assignments - description: Creates products channel assignments. - operationId: CreateProductsChannelAssignments - parameters: - - $ref: '#/components/parameters/ContentType' - tags: - - Products Channel Assignments - requestBody: - required: true - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ProductChannelAssignment' - responses: - '204': - description: Updated - '422': - description: Error response for batch PUT of Channel Assignments. Includes the errors for each reference id. - content: - application/json: - schema: - $ref: '#/components/schemas/beta5ErrorResponse' - delete: - summary: Delete Products Channel Assignments - description: Delete products channel assignments. A filter must be supplied. - operationId: DeleteProductsChannelAssignments - tags: - - Products Channel Assignments - parameters: - - name: 'product_id:in' - in: query - schema: - type: string - - name: 'channel_id:in' - in: query - schema: - type: string - responses: - '204': - description: Deleted - '422': - description: At least one filter must be provided in order to delete channel assignments - content: - application/json: - schema: - $ref: '#/components/schemas/beta5ErrorResponse' - parameters: - - $ref: '#/components/parameters/Accept' - '/catalog/products/category-assignments': - get: - summary: Get Products Category Assignments - description: Returns a list of products category assignments. - operationId: GetProductsCategoryAssignments - tags: - - Products Category Assignments - parameters: - - name: page - in: query - schema: - type: integer - - name: limit - in: query - schema: - type: integer - - name: 'product_id:in' - in: query - schema: - type: string - - name: 'category_id:in' - in: query - schema: - type: string - responses: - '200': - description: Collection of category assignments. - content: - application/json: - schema: - type: object - properties: - data: - type: array - items: - $ref: '#/components/schemas/ProductCategoryAssignment' - meta: - $ref: '#/components/schemas/MetaPaginationObject' - put: - summary: Create Products Category Assignments. - description: Creates products category assignments. - operationId: CreateProductsCategoryAssignments - parameters: - - $ref: '#/components/parameters/ContentType' - tags: - - Products Category Assignments - requestBody: - required: true - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/ProductCategoryAssignment' - responses: - '204': - description: Updated - '422': - description: Error response for batch PUT of Category Assignments. Includes the errors for each reference id. - content: - application/json: - schema: - $ref: '#/components/schemas/beta5ErrorResponse' - delete: - summary: Delete Products Category Assignments - description: Deletes products category assignments. A filter must be supplied. - operationId: DeleteProductsCategoryAssignments - tags: - - Products Category Assignments - parameters: - - name: 'product_id:in' - in: query - schema: - type: string - - name: 'category_id:in' - in: query - schema: - type: string - responses: - '204': - description: Deleted - '422': - description: At least one filter must be provided in order to delete category assignments - content: - application/json: - schema: - $ref: '#/components/schemas/beta5ErrorResponse' - parameters: - - $ref: '#/components/parameters/Accept' -components: - schemas: - formData_ImageFileParam: - type: string - description: | - An image file. Supported MIME types include GIF, JPEG, and PNG. - format: binary - productModifier_Base: - title: productModifier_Base - required: - - required - - type - type: object - properties: - type: - type: string - description: | - BigCommerce API, which determines how it will display on the storefront. Acceptable values: `date`, `checkbox`, `file`, `text`, `multi_line_text`, `numbers_only_text`, `radio_buttons`, `rectangles`, `dropdown`, `product_list`, `product_list_with_images`, `swatch`. Required in a /POST. - enum: - - date - - checkbox - - file - - text - - multi_line_text - - numbers_only_text - - radio_buttons - - rectangles - - dropdown - - product_list - - product_list_with_images - - swatch - x-required: - - post - required: - type: boolean - description: | - Whether or not this modifer is required or not at checkout. Required in a /POST. - x-required: - - post - sort_order: - type: integer - description: The order the modifiers display on the product detail page. - config: - $ref: '#/components/schemas/config_Full' - display_name: - type: string - description: The name of the option shown on the storefront. - description: Common Modifier properties. - x-internal: false - productModifier_Full: - title: productModifier_Full - description: Product Modifier - allOf: - - $ref: '#/components/schemas/productModifier_Base' - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the modifier; increments sequentially. - example: 12 - product_id: - type: integer - description: | - The unique numeric ID of the product to which the option belongs. - example: 77 - name: - type: string - description: | - The unique option name. Auto-generated from the display name, a timestamp, and the product ID. - example: Add-a-$5-Donation1535039590-191 - option_values: - type: array - items: - $ref: '#/components/schemas/productModifierOptionValue_Full' - x-internal: false - productModifier_Post: - title: productModifier_Post - description: The model for a POST to create a modifier on a product. - allOf: - - title: Modifier Base - required: - - required - - type - type: object - properties: - type: - type: string - description: | - BigCommerce API, which determines how it will display on the storefront. Acceptable values: `date`, `checkbox`, `file`, `text`, `multi_line_text`, `numbers_only_text`, `radio_buttons`, `rectangles`, `dropdown`, `product_list`, `product_list_with_images`, `swatch`. Required in a /POST. - enum: - - date - - checkbox - - file - - text - - multi_line_text - - numbers_only_text - - radio_buttons - - rectangles - - dropdown - - product_list - - product_list_with_images - - swatch - x-required: - - post - required: - type: boolean - description: | - Whether or not this modifer is required or not at checkout. Required in a /POST. - x-required: - - post - sort_order: - type: integer - description: The order the modifiers display on the product detail page. - config: - title: Option Config - type: object - properties: - default_value: - type: string - description: | - (date, text, multi_line_text, numbers_only_text) The default value. Shown on a date option as an ISO-8601–formatted string, or on a text option as a string. - checked_by_default: - type: boolean - description: | - (checkbox) Flag for setting the checkbox to be checked by default. - checkbox_label: - type: string - description: | - (checkbox) Label displayed for the checkbox option. - date_limited: - type: boolean - description: | - (date) Flag to limit the dates allowed to be entered on a date option. - date_limit_mode: - type: string - description: | - (date) The type of limit that is allowed to be entered on a date option. - example: range - enum: - - earliest - - range - - latest - date_earliest_value: - type: string - description: | - (date) The earliest date allowed to be entered on the date option, as an ISO-8601 formatted string. - format: date - date_latest_value: - type: string - description: | - (date) The latest date allowed to be entered on the date option, as an ISO-8601 formatted string. - format: date - file_types_mode: - type: string - description: | - (file) The kind of restriction on the file types that can be uploaded with a file upload option. Values: `specific` - restricts uploads to particular file types; `all` - allows all file types. - example: specific - enum: - - specific - - all - file_types_supported: - type: array - description: | - (file) The type of files allowed to be uploaded if the `file_type_option` is set to `specific`. Values: - `images` - Allows upload of image MIME types (`bmp`, `gif`, `jpg`, `jpeg`, `jpe`, `jif`, `jfif`, `jfi`, `png`, `wbmp`, `xbm`, `tiff`). `documents` - Allows upload of document MIME types (`txt`, `pdf`, `rtf`, `doc`, `docx`, `xls`, `xlsx`, `accdb`, `mdb`, `one`, `pps`, `ppsx`, `ppt`, `pptx`, `pub`, `odt`, `ods`, `odp`, `odg`, `odf`). - `other` - Allows file types defined in the `file_types_other` array. - items: - type: string - example: 'images, documents, other' - file_types_other: - type: array - description: | - (file) A list of other file types allowed with the file upload option. - items: - type: string - example: pdf - file_max_size: - type: integer - description: | - (file) The maximum size for a file that can be used with the file upload option. This will still be limited by the server. - example: 5 - text_characters_limited: - type: boolean - description: | - (text, multi_line_text) Flag to validate the length of a text or multi-line text input. - text_min_length: - type: integer - description: | - (text, multi_line_text) The minimum length allowed for a text or multi-line text option. - example: 1 - text_max_length: - type: integer - description: | - (text, multi_line_text) The maximum length allowed for a text or multi line text option. - example: 55 - text_lines_limited: - type: boolean - description: | - (multi_line_text) Flag to validate the maximum number of lines allowed on a multi-line text input. - example: true - text_max_lines: - type: integer - description: | - (multi_line_text) The maximum number of lines allowed on a multi-line text input. - example: 4 - number_limited: - type: boolean - description: | - (numbers_only_text) Flag to limit the value of a number option. - example: true - number_limit_mode: - type: string - description: | - (numbers_only_text) The type of limit on values entered for a number option. - example: lowest - enum: - - lowest - - highest - - range - number_lowest_value: - type: number - description: | - (numbers_only_text) The lowest allowed value for a number option if `number_limited` is true. - example: 100 - number_highest_value: - type: number - description: | - (numbers_only_text) The highest allowed value for a number option if `number_limited` is true. - number_integers_only: - type: boolean - description: | - (numbers_only_text) Flag to limit the input on a number option to whole numbers only. - example: false - product_list_adjusts_inventory: - type: boolean - description: | - (product_list, product_list_with_images) Flag for automatically adjusting inventory on a product included in the list. - product_list_adjusts_pricing: - type: boolean - description: | - (product_list, product_list_with_images) Flag to add the optional product's price to the main product's price. - product_list_shipping_calc: - type: string - description: | - (product_list, product_list_with_images) How to factor the optional product's weight and package dimensions into the shipping quote. Values: `none` - don't adjust; `weight` - use shipping weight only; `package` - use weight and dimensions. - example: weight - enum: - - none - - weight - - package - description: The values for option config can vary based on the Modifier created. - option_values: - type: array - items: - title: Modifier Value - type: object - description: 'Part of Modifier Value Response ' - allOf: - - title: Modifier Value Base - type: object - allOf: - - title: Option Value Base - required: - - label - - sort_order - type: object - properties: - is_default: - type: boolean - description: | - The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. - example: false - label: - type: string - description: | - The text display identifying the value on the storefront. Required in a /POST. - example: Green - x-required: - - post - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the value will be displayed on the product page. Required in a /POST. - example: 0 - x-required: - - post - value_data: - type: object - properties: {} - description: | - Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. - description: Common Option Value properties. - - type: object - properties: - adjusters: - type: object - properties: - price: - title: Adjuster - type: object - properties: - adjuster: - type: string - description: | - The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - enum: - - relative - - percentage - x-nullable: true - adjuster_value: - type: number - description: | - The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. - example: 5 - description: Adjuster for Complex Rules. - weight: - title: Adjuster - type: object - properties: - adjuster: - type: string - description: | - The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - enum: - - relative - - percentage - x-nullable: true - adjuster_value: - type: number - description: | - The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. - example: 5 - description: Adjuster for Complex Rules. - image_url: - type: string - description: | - The URL for an image displayed on the storefront when the modifier value is selected.Limit of 8MB per file. - example: 'https://cdn8.bigcommerce.com/s-{{store_hash}}/products/184/images/445/naturalcanvascart2_1024x1024__92347__29648.1534344533.1280.1280.jpg?c=2' - purchasing_disabled: - type: object - properties: - status: - type: boolean - description: | - Flag for whether the modifier value disables purchasing when selected on the storefront. This can be used for temporarily disabling a particular modifier value. - message: - type: string - description: | - The message displayed on the storefront when the purchasing disabled status is `true`. - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the value; increments sequentially. - description: Common Modifier properties. - - required: - - display_name - type: object - properties: - display_name: - type: string - description: | - The name of the option shown on the storefront. - example: Donation - x-required: - - post - x-internal: false - productModifier_Put: - title: productModifier_Put - description: The model for a PUT to update a modifier on a product. - allOf: - - title: Modifier Base - required: - - required - - type - type: object - properties: - type: - type: string - description: | - BigCommerce API, which determines how it will display on the storefront. Acceptable values: `date`, `checkbox`, `file`, `text`, `multi_line_text`, `numbers_only_text`, `radio_buttons`, `rectangles`, `dropdown`, `product_list`, `product_list_with_images`, `swatch`. Required in a /POST. - enum: - - date - - checkbox - - file - - text - - multi_line_text - - numbers_only_text - - radio_buttons - - rectangles - - dropdown - - product_list - - product_list_with_images - - swatch - x-required: - - post - required: - type: boolean - description: | - Whether or not this modifer is required or not at checkout. Required in a /POST. - x-required: - - post - sort_order: - type: integer - description: The order the modifiers display on the product detail page. - config: - title: Option Config - type: object - properties: - default_value: - type: string - description: | - (date, text, multi_line_text, numbers_only_text) The default value. Shown on a date option as an ISO-8601–formatted string, or on a text option as a string. - checked_by_default: - type: boolean - description: | - (checkbox) Flag for setting the checkbox to be checked by default. - checkbox_label: - type: string - description: | - (checkbox) Label displayed for the checkbox option. - date_limited: - type: boolean - description: | - (date) Flag to limit the dates allowed to be entered on a date option. - date_limit_mode: - type: string - description: | - (date) The type of limit that is allowed to be entered on a date option. - example: range - enum: - - earliest - - range - - latest - date_earliest_value: - type: string - description: | - (date) The earliest date allowed to be entered on the date option, as an ISO-8601 formatted string. - format: date - date_latest_value: - type: string - description: | - (date) The latest date allowed to be entered on the date option, as an ISO-8601 formatted string. - format: date - file_types_mode: - type: string - description: | - (file) The kind of restriction on the file types that can be uploaded with a file upload option. Values: `specific` - restricts uploads to particular file types; `all` - allows all file types. - example: specific - enum: - - specific - - all - file_types_supported: - type: array - description: | - (file) The type of files allowed to be uploaded if the `file_type_option` is set to `specific`. Values: - `images` - Allows upload of image MIME types (`bmp`, `gif`, `jpg`, `jpeg`, `jpe`, `jif`, `jfif`, `jfi`, `png`, `wbmp`, `xbm`, `tiff`). `documents` - Allows upload of document MIME types (`txt`, `pdf`, `rtf`, `doc`, `docx`, `xls`, `xlsx`, `accdb`, `mdb`, `one`, `pps`, `ppsx`, `ppt`, `pptx`, `pub`, `odt`, `ods`, `odp`, `odg`, `odf`). - `other` - Allows file types defined in the `file_types_other` array. - items: - type: string - example: 'images, documents, other' - file_types_other: - type: array - description: | - (file) A list of other file types allowed with the file upload option. - items: - type: string - example: pdf - file_max_size: - type: integer - description: | - (file) The maximum size for a file that can be used with the file upload option. This will still be limited by the server. - example: 5 - text_characters_limited: - type: boolean - description: | - (text, multi_line_text) Flag to validate the length of a text or multi-line text input. - text_min_length: - type: integer - description: | - (text, multi_line_text) The minimum length allowed for a text or multi-line text option. - example: 1 - text_max_length: - type: integer - description: | - (text, multi_line_text) The maximum length allowed for a text or multi line text option. - example: 55 - text_lines_limited: - type: boolean - description: | - (multi_line_text) Flag to validate the maximum number of lines allowed on a multi-line text input. - example: true - text_max_lines: - type: integer - description: | - (multi_line_text) The maximum number of lines allowed on a multi-line text input. - example: 4 - number_limited: - type: boolean - description: | - (numbers_only_text) Flag to limit the value of a number option. - example: true - number_limit_mode: - type: string - description: | - (numbers_only_text) The type of limit on values entered for a number option. - example: lowest - enum: - - lowest - - highest - - range - number_lowest_value: - type: number - description: | - (numbers_only_text) The lowest allowed value for a number option if `number_limited` is true. - example: 100 - number_highest_value: - type: number - description: | - (numbers_only_text) The highest allowed value for a number option if `number_limited` is true. - number_integers_only: - type: boolean - description: | - (numbers_only_text) Flag to limit the input on a number option to whole numbers only. - example: false - product_list_adjusts_inventory: - type: boolean - description: | - (product_list, product_list_with_images) Flag for automatically adjusting inventory on a product included in the list. - product_list_adjusts_pricing: - type: boolean - description: | - (product_list, product_list_with_images) Flag to add the optional product's price to the main product's price. - product_list_shipping_calc: - type: string - description: | - (product_list, product_list_with_images) How to factor the optional product's weight and package dimensions into the shipping quote. Values: `none` - don't adjust; `weight` - use shipping weight only; `package` - use weight and dimensions. - example: weight - enum: - - none - - weight - - package - description: The values for option config can vary based on the Modifier created. - option_values: - type: array - items: - title: Modifier Value - type: object - description: 'Part of Modifier Value Response ' - allOf: - - title: Modifier Value Base - type: object - allOf: - - title: Option Value Base - required: - - label - - sort_order - type: object - properties: - is_default: - type: boolean - description: | - The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. - example: false - label: - type: string - description: | - The text display identifying the value on the storefront. Required in a /POST. - example: Green - x-required: - - post - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the value will be displayed on the product page. Required in a /POST. - example: 0 - x-required: - - post - value_data: - type: object - properties: {} - description: | - Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. - description: Common Option Value properties. - - type: object - properties: - adjusters: - type: object - properties: - price: - title: Adjuster - type: object - properties: - adjuster: - type: string - description: | - The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - enum: - - relative - - percentage - x-nullable: true - adjuster_value: - type: number - description: | - The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. - example: 5 - description: Adjuster for Complex Rules. - weight: - title: Adjuster - type: object - properties: - adjuster: - type: string - description: | - The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - enum: - - relative - - percentage - x-nullable: true - adjuster_value: - type: number - description: | - The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. - example: 5 - description: Adjuster for Complex Rules. - image_url: - type: string - description: | - The URL for an image displayed on the storefront when the modifier value is selected.Limit of 8MB per file. - example: 'https://cdn8.bigcommerce.com/s-{{store_hash}}/products/184/images/445/naturalcanvascart2_1024x1024__92347__29648.1534344533.1280.1280.jpg?c=2' - purchasing_disabled: - type: object - properties: - status: - type: boolean - description: | - Flag for whether the modifier value disables purchasing when selected on the storefront. This can be used for temporarily disabling a particular modifier value. - message: - type: string - description: | - The message displayed on the storefront when the purchasing disabled status is `true`. - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the value; increments sequentially. - description: Common Modifier properties. - x-internal: false - productModifierOptionValue_Base: - title: productModifierOptionValue_Base - required: - - label - - sort_order - type: object - properties: - is_default: - type: boolean - description: | - The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. - example: false - label: - type: string - description: | - The text display identifying the value on the storefront. Required in a /POST. - example: Green - x-required: - - post - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the value will be displayed on the product page. Required in a /POST. - example: 0 - x-required: - - post - value_data: - type: object - properties: {} - description: | - Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. If no data is available, returns `null`. - nullable: true - adjusters: - $ref: '#/components/schemas/adjusters_Full' - description: Common Product Modifer `option_value` properties. - x-internal: false - productModifierOptionValue_Full: - title: productModifierOptionValue_Full - description: Product Modifer `option_value`. - allOf: - - $ref: '#/components/schemas/productModifierOptionValue_Base' - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the value; increments sequentially. - option_id: - type: integer - x-internal: false - productModifierOptionValue_Post: - title: productModifierOptionValue_Post - description: The model for a POST to create a modifier value on a product. - allOf: - - title: Modifier Value Base - allOf: - - title: Option Value Base - required: - - label - - sort_order - type: object - properties: - is_default: - type: boolean - description: | - The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. - example: false - label: - type: string - description: | - The text display identifying the value on the storefront. Required in a /POST. - example: Green - x-required: - - post - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the value will be displayed on the product page. Required in a /POST. - example: 0 - x-required: - - post - value_data: - type: object - properties: {} - description: | - Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. - description: Common Option Value properties. - - type: object - properties: - adjusters: - type: object - properties: - price: - title: Adjuster - type: object - properties: - adjuster: - type: string - description: | - The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - nullable: true - enum: - - relative - - percentage - adjuster_value: - type: number - description: | - The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. - example: 5 - description: Adjuster for Complex Rules. - weight: - title: Adjuster - type: object - properties: - adjuster: - type: string - description: | - The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - nullable: true - enum: - - relative - - percentage - adjuster_value: - type: number - description: | - The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. - example: 5 - description: Adjuster for Complex Rules. - image_url: - type: string - description: | - The URL for an image displayed on the storefront when the modifier value is selected.Limit of 8MB per file. - example: 'https://cdn8.bigcommerce.com/s-{{store_hash}}/products/184/images/445/naturalcanvascart2_1024x1024__92347__29648.1534344533.1280.1280.jpg?c=2' - purchasing_disabled: - type: object - properties: - status: - type: boolean - description: | - Flag for whether the modifier value disables purchasing when selected on the storefront. This can be used for temporarily disabling a particular modifier value. - message: - type: string - description: | - The message displayed on the storefront when the purchasing disabled status is `true`. - x-internal: false - productModifierOptionValue_Put: - title: productModifierOptionValue_Put - description: The model for a PUT to update a modifier value on a product. - allOf: - - title: Modifier Value Base - allOf: - - title: Option Value Base - required: - - label - - sort_order - type: object - properties: - is_default: - type: boolean - description: | - The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. - example: false - label: - type: string - description: | - The text display identifying the value on the storefront. Required in a /POST. - example: Green - x-required: - - post - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the value will be displayed on the product page. Required in a /POST. - example: 0 - x-required: - - post - value_data: - type: object - properties: {} - description: | - Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. - description: Common Option Value properties. - - type: object - properties: - adjusters: - type: object - properties: - price: - title: Adjuster - type: object - properties: - adjuster: - type: string - description: | - The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - nullable: true - enum: - - relative - - percentage - adjuster_value: - type: number - description: | - The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. - example: 5 - description: Adjuster for Complex Rules. - weight: - title: Adjuster - type: object - properties: - adjuster: - type: string - description: | - The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - nullable: true - enum: - - relative - - percentage - adjuster_value: - type: number - description: | - The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. - example: 5 - description: Adjuster for Complex Rules. - image_url: - type: string - description: | - The URL for an image displayed on the storefront when the modifier value is selected.Limit of 8MB per file. - example: 'https://cdn8.bigcommerce.com/s-{{store_hash}}/products/184/images/445/naturalcanvascart2_1024x1024__92347__29648.1534344533.1280.1280.jpg?c=2' - purchasing_disabled: - type: object - properties: - status: - type: boolean - description: | - Flag for whether the modifier value disables purchasing when selected on the storefront. This can be used for temporarily disabling a particular modifier value. - message: - type: string - description: | - The message displayed on the storefront when the purchasing disabled status is `true`. - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the value; increments sequentially. - x-required: - - put - x-internal: false - resp_productionOption: - title: resp_productionOption - type: object - properties: - data: - $ref: '#/components/schemas/productOption_Full' - meta: - title: Meta - type: object - properties: - 'null': - type: string - description: Empty meta object; may be used later. - x-internal: false - productOption_Base: - title: productOption_Base - type: object - properties: - id: - type: integer - description: | - The unique numerical ID of the option, increments sequentially. - nullable: true - example: 55 - product_id: - type: integer - description: | - The unique numerical ID of the product to which the option belongs. - example: 4 - x-required: - - post - - put - display_name: - maxLength: 255 - minLength: 1 - type: string - description: | - The name of the option shown on the storefront. - example: Add-a-$5-Donation1535042499-187 - x-required: - - post - - put - type: - type: string - description: | - The type of option, which determines how it will display on the storefront. Acceptable values: `radio_buttons`, `rectangles`, `dropdown`, `product_list`, `product_list_with_images`, `swatch`. For reference, the former v2 API values are: RB = radio_buttons, RT = rectangles, S = dropdown, P = product_list, PI = product_list_with_images, CS = swatch. - enum: - - radio_buttons - - rectangles - - dropdown - - product_list - - product_list_with_images - - swatch - x-required: - - post - - put - config: - $ref: '#/components/schemas/productOptionConfig_Full' - sort_order: - type: integer - description: 'Order in which the option is displayed on the storefront. ' - example: 1 - option_values: - $ref: '#/components/schemas/productOptionOptionValue_Full' - description: Common Option properties. - x-internal: false - productOption_Full: - title: productOption_Full - allOf: - - $ref: '#/components/schemas/productOption_Base' - - type: object - properties: - name: - type: string - description: | - The unique option name, auto-generated from the display name, a timestamp, and the product ID. - example: Add-a-$5-Donation1535042499-187 - x-internal: false - productOption_Post: - title: productOption_Post - description: The model for a POST to create options on a product. - allOf: - - title: Option Base - type: object - properties: - id: - type: integer - description: | - The unique numerical ID of the option, increments sequentially. - nullable: true - example: 55 - product_id: - type: integer - description: | - The unique numerical ID of the product to which the option belongs. - example: 4 - x-required: - - post - - put - display_name: - maxLength: 255 - minLength: 1 - type: string - description: | - The name of the option shown on the storefront. - example: Add-a-$5-Donation1535042499-187 - x-required: - - post - - put - type: - type: string - description: | - The type of option, which determines how it will display on the storefront. Acceptable values: `radio_buttons`, `rectangles`, `dropdown`, `product_list`, `product_list_with_images`, `swatch`. For reference, the former v2 API values are: RB = radio_buttons, RT = rectangles, S = dropdown, P = product_list, PI = product_list_with_images, CS = swatch. - enum: - - radio_buttons - - rectangles - - dropdown - - product_list - - product_list_with_images - - swatch - x-required: - - post - - put - config: - title: Option Config - type: object - properties: - default_value: - type: string - description: | - (date, text, multi_line_text, numbers_only_text) The default value. Shown on a date option as an ISO-8601–formatted string, or on a text option as a string. - checked_by_default: - type: boolean - description: | - (checkbox) Flag for setting the checkbox to be checked by default. - checkbox_label: - type: string - description: | - (checkbox) Label displayed for the checkbox option. - date_limited: - type: boolean - description: | - (date) Flag to limit the dates allowed to be entered on a date option. - date_limit_mode: - type: string - description: | - (date) The type of limit that is allowed to be entered on a date option. - example: range - enum: - - earliest - - range - - latest - date_earliest_value: - type: string - description: | - (date) The earliest date allowed to be entered on the date option, as an ISO-8601 formatted string. - format: date - date_latest_value: - type: string - description: | - (date) The latest date allowed to be entered on the date option, as an ISO-8601 formatted string. - format: date - file_types_mode: - type: string - description: | - (file) The kind of restriction on the file types that can be uploaded with a file upload option. Values: `specific` - restricts uploads to particular file types; `all` - allows all file types. - example: specific - enum: - - specific - - all - file_types_supported: - type: array - description: | - (file) The type of files allowed to be uploaded if the `file_type_option` is set to `specific`. Values: - `images` - Allows upload of image MIME types (`bmp`, `gif`, `jpg`, `jpeg`, `jpe`, `jif`, `jfif`, `jfi`, `png`, `wbmp`, `xbm`, `tiff`). `documents` - Allows upload of document MIME types (`txt`, `pdf`, `rtf`, `doc`, `docx`, `xls`, `xlsx`, `accdb`, `mdb`, `one`, `pps`, `ppsx`, `ppt`, `pptx`, `pub`, `odt`, `ods`, `odp`, `odg`, `odf`). - `other` - Allows file types defined in the `file_types_other` array. - items: - type: string - example: 'images, documents, other' - file_types_other: - type: array - description: | - (file) A list of other file types allowed with the file upload option. - items: - type: string - example: pdf - file_max_size: - type: integer - description: | - (file) The maximum size for a file that can be used with the file upload option. This will still be limited by the server. - example: 5 - text_characters_limited: - type: boolean - description: | - (text, multi_line_text) Flag to validate the length of a text or multi-line text input. - text_min_length: - type: integer - description: | - (text, multi_line_text) The minimum length allowed for a text or multi-line text option. - example: 1 - text_max_length: - type: integer - description: | - (text, multi_line_text) The maximum length allowed for a text or multi line text option. - example: 55 - text_lines_limited: - type: boolean - description: | - (multi_line_text) Flag to validate the maximum number of lines allowed on a multi-line text input. - example: true - text_max_lines: - type: integer - description: | - (multi_line_text) The maximum number of lines allowed on a multi-line text input. - example: 4 - number_limited: - type: boolean - description: | - (numbers_only_text) Flag to limit the value of a number option. - example: true - number_limit_mode: - type: string - description: | - (numbers_only_text) The type of limit on values entered for a number option. - example: lowest - enum: - - lowest - - highest - - range - number_lowest_value: - type: number - description: | - (numbers_only_text) The lowest allowed value for a number option if `number_limited` is true. - example: 100 - number_highest_value: - type: number - description: | - (numbers_only_text) The highest allowed value for a number option if `number_limited` is true. - number_integers_only: - type: boolean - description: | - (numbers_only_text) Flag to limit the input on a number option to whole numbers only. - example: false - product_list_adjusts_inventory: - type: boolean - description: | - (product_list, product_list_with_images) Flag for automatically adjusting inventory on a product included in the list. - product_list_adjusts_pricing: - type: boolean - description: | - (product_list, product_list_with_images) Flag to add the optional product's price to the main product's price. - product_list_shipping_calc: - type: string - description: | - (product_list, product_list_with_images) How to factor the optional product's weight and package dimensions into the shipping quote. Values: `none` - don't adjust; `weight` - use shipping weight only; `package` - use weight and dimensions. - example: weight - enum: - - none - - weight - - package - description: The values for option config can vary based on the Modifier created. - sort_order: - type: integer - description: 'Order in which the option is displayed on the storefront. ' - example: 1 - option_values: - minItems: 1 - type: array - items: - title: Option Value - type: object - allOf: - - title: Option Value Base - required: - - label - - sort_order - type: object - properties: - is_default: - type: boolean - description: | - The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. - example: false - label: - type: string - description: | - The text display identifying the value on the storefront. Required in a /POST. - example: Green - x-required: - - post - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the value will be displayed on the product page. Required in a /POST. - example: 0 - x-required: - - post - value_data: - type: object - properties: {} - description: | - Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. - description: Common Option Value properties. - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the value; increments sequentially. - x-required: - - post - - put - image_url: - type: string - description: Publicly available image url - description: Common Option properties. - x-internal: false - productOption_Put: - title: productOption_Put - description: The model for a PUT to update options on a product. - allOf: - - title: Option Base - type: object - properties: - id: - type: integer - description: | - The unique numerical ID of the option, increments sequentially. - nullable: true - example: 55 - product_id: - type: integer - description: | - The unique numerical ID of the product to which the option belongs. - example: 4 - x-required: - - post - - put - display_name: - maxLength: 255 - minLength: 1 - type: string - description: | - The name of the option shown on the storefront. - example: Add-a-$5-Donation1535042499-187 - x-required: - - post - - put - type: - type: string - description: | - The type of option, which determines how it will display on the storefront. Acceptable values: `radio_buttons`, `rectangles`, `dropdown`, `product_list`, `product_list_with_images`, `swatch`. For reference, the former v2 API values are: RB = radio_buttons, RT = rectangles, S = dropdown, P = product_list, PI = product_list_with_images, CS = swatch. - enum: - - radio_buttons - - rectangles - - dropdown - - product_list - - product_list_with_images - - swatch - x-required: - - post - - put - config: - title: Option Config - type: object - properties: - default_value: - type: string - description: | - (date, text, multi_line_text, numbers_only_text) The default value. Shown on a date option as an ISO-8601–formatted string, or on a text option as a string. - checked_by_default: - type: boolean - description: | - (checkbox) Flag for setting the checkbox to be checked by default. - checkbox_label: - type: string - description: | - (checkbox) Label displayed for the checkbox option. - date_limited: - type: boolean - description: | - (date) Flag to limit the dates allowed to be entered on a date option. - date_limit_mode: - type: string - description: | - (date) The type of limit that is allowed to be entered on a date option. - example: range - enum: - - earliest - - range - - latest - date_earliest_value: - type: string - description: | - (date) The earliest date allowed to be entered on the date option, as an ISO-8601 formatted string. - format: date - date_latest_value: - type: string - description: | - (date) The latest date allowed to be entered on the date option, as an ISO-8601 formatted string. - format: date - file_types_mode: - type: string - description: | - (file) The kind of restriction on the file types that can be uploaded with a file upload option. Values: `specific` - restricts uploads to particular file types; `all` - allows all file types. - example: specific - enum: - - specific - - all - file_types_supported: - type: array - description: | - (file) The type of files allowed to be uploaded if the `file_type_option` is set to `specific`. Values: - `images` - Allows upload of image MIME types (`bmp`, `gif`, `jpg`, `jpeg`, `jpe`, `jif`, `jfif`, `jfi`, `png`, `wbmp`, `xbm`, `tiff`). `documents` - Allows upload of document MIME types (`txt`, `pdf`, `rtf`, `doc`, `docx`, `xls`, `xlsx`, `accdb`, `mdb`, `one`, `pps`, `ppsx`, `ppt`, `pptx`, `pub`, `odt`, `ods`, `odp`, `odg`, `odf`). - `other` - Allows file types defined in the `file_types_other` array. - items: - type: string - example: 'images, documents, other' - file_types_other: - type: array - description: | - (file) A list of other file types allowed with the file upload option. - items: - type: string - example: pdf - file_max_size: - type: integer - description: | - (file) The maximum size for a file that can be used with the file upload option. This will still be limited by the server. - example: 5 - text_characters_limited: - type: boolean - description: | - (text, multi_line_text) Flag to validate the length of a text or multi-line text input. - text_min_length: - type: integer - description: | - (text, multi_line_text) The minimum length allowed for a text or multi-line text option. - example: 1 - text_max_length: - type: integer - description: | - (text, multi_line_text) The maximum length allowed for a text or multi line text option. - example: 55 - text_lines_limited: - type: boolean - description: | - (multi_line_text) Flag to validate the maximum number of lines allowed on a multi-line text input. - example: true - text_max_lines: - type: integer - description: | - (multi_line_text) The maximum number of lines allowed on a multi-line text input. - example: 4 - number_limited: - type: boolean - description: | - (numbers_only_text) Flag to limit the value of a number option. - example: true - number_limit_mode: - type: string - description: | - (numbers_only_text) The type of limit on values entered for a number option. - example: lowest - enum: - - lowest - - highest - - range - number_lowest_value: - type: number - description: | - (numbers_only_text) The lowest allowed value for a number option if `number_limited` is true. - example: 100 - number_highest_value: - type: number - description: | - (numbers_only_text) The highest allowed value for a number option if `number_limited` is true. - number_integers_only: - type: boolean - description: | - (numbers_only_text) Flag to limit the input on a number option to whole numbers only. - example: false - product_list_adjusts_inventory: - type: boolean - description: | - (product_list, product_list_with_images) Flag for automatically adjusting inventory on a product included in the list. - product_list_adjusts_pricing: - type: boolean - description: | - (product_list, product_list_with_images) Flag to add the optional product's price to the main product's price. - product_list_shipping_calc: - type: string - description: | - (product_list, product_list_with_images) How to factor the optional product's weight and package dimensions into the shipping quote. Values: `none` - don't adjust; `weight` - use shipping weight only; `package` - use weight and dimensions. - example: weight - enum: - - none - - weight - - package - description: The values for option config can vary based on the Modifier created. - sort_order: - type: integer - description: 'Order in which the option is displayed on the storefront. ' - example: 1 - option_values: - minItems: 1 - type: array - items: - title: Option Value - type: object - allOf: - - title: Option Value Base - required: - - label - - sort_order - type: object - properties: - is_default: - type: boolean - description: | - The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. - example: false - label: - type: string - description: | - The text display identifying the value on the storefront. Required in a /POST. - example: Green - x-required: - - post - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the value will be displayed on the product page. Required in a /POST. - example: 0 - x-required: - - post - value_data: - type: object - properties: {} - description: | - Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. - description: Common Option Value properties. - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the value; increments sequentially. - x-required: - - post - - put - image_url: - type: string - description: Publicly available image url - description: Common Option properties. - x-internal: false - categoriesTree_Resp: - title: categoriesTree_Resp - type: object - properties: - data: - type: array - items: - $ref: '#/components/schemas/categoriesTreeNode_Full' - meta: - $ref: '#/components/schemas/metaEmpty_Full' - description: | - Returns the categories tree, a nested lineage of the categories with parent->child relationship. The Category objects returned are simplified versions of the category objects returned in the rest of this API. - x-internal: false - categoriesTreeNode_Full: - title: categoriesTreeNode_Full - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the category; increments sequentially. - example: 26 - parent_id: - type: integer - description: | - The unique numeric ID of the category's parent. This field controls where the category sits in the tree of categories that organize the catalog. - example: 25 - name: - type: string - description: | - The name displayed for the category. Name is unique with respect to the category's siblings. - example: Bath - is_visible: - type: boolean - description: | - Flag to determine whether the product should be displayed to customers browsing the store. If `true`, the category will be displayed. If `false`, the category will be hidden from view. - example: true - url: - type: string - description: | - The custom URL for the category on the storefront. - example: /towels/bath-towels/ - description: Used to reflect parent <> child category relationships. Used by Category Tree. - x-internal: false - category_Full: - title: category_Full - type: object - description: Common Category object properties. - x-internal: false - properties: - id: - type: integer - description: |- - Unique ID of the *Category*. Increments sequentially. - Read-Only. - readOnly: true - parent_id: - type: integer - description: |- - The unique numeric ID of the category's parent. This field controls where the category sits in the tree of categories that organize the catalog. - Required in a POST if creating a child category. - example: 2 - x-required: - - post - name: - maxLength: 50 - minLength: 1 - type: string - description: |- - The name displayed for the category. Name is unique with respect to the category's siblings. - Required in a POST. - example: Bath - x-required: - - post - description: - type: string - description: | - The product description, which can include HTML formatting. - example: <p>We offer a wide variety of products perfect for relaxing</p> - views: - type: integer - description: | - Number of views the category has on the storefront. - example: 1050 - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - Priority this category will be given when included in the menu and category pages. The lower the number, the closer to the top of the results the category will be. - example: 3 - page_title: - maxLength: 255 - minLength: 0 - type: string - description: | - Custom title for the category page. If not defined, the category name will be used as the meta title. - example: Bath - search_keywords: - maxLength: 255 - minLength: 0 - type: string - description: | - A comma-separated list of keywords that can be used to locate the category when searching the store. - meta_keywords: - type: array - description: | - Custom meta keywords for the category page. If not defined, the store's default keywords will be used. Must post as an array like: ["awesome","sauce"]. - items: - type: string - meta_description: - maxLength: 65535 - minLength: 0 - type: string - description: | - Custom meta description for the category page. If not defined, the store's default meta description will be used. - layout_file: - maxLength: 500 - minLength: 0 - type: string - description: | - A valid layout file. (Please refer to [this article](https://support.bigcommerce.com/articles/Public/Creating-Custom-Template-Files/) on creating category files.) This field is writable only for stores with a Blueprint theme applied. For stores with a Stencil theme applied, see [Custom Template Associations](https://developer.bigcommerce.com/api-reference/store-management/custom-template-associations). - example: category.html - is_visible: - type: boolean - description: | - Flag to determine whether the product should be displayed to customers browsing the store. If `true`, the category will be displayed. If `false`, the category will be hidden from view. - default_product_sort: - type: string - description: | - Determines how the products are sorted on category page load. - enum: - - use_store_settings - - featured - - newest - - best_selling - - alpha_asc - - alpha_desc - - avg_customer_review - - price_asc - - price_desc - image_url: - type: string - description: | - Image URL used for this category on the storefront. Images can be uploaded via form file post to `/categories/{categoryId}/image`, or by providing a publicly accessible URL in this field. - example: 'https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png' - x-url: true - custom_url: - $ref: '#/components/schemas/customUrl_Full' - required: - - parent_id - - name - brand_Full: - title: brand_Full - required: - - name - type: object - properties: - id: - type: integer - description: Unique ID of the *Brand*. Read-Only. - readOnly: true - name: - maxLength: 255 - minLength: 1 - type: string - description: |- - The name of the brand. Must be unique. - Required in POST. - example: Common Good - x-required: - - post - - put - page_title: - maxLength: 255 - minLength: 0 - type: string - description: | - The title shown in the browser while viewing the brand. - example: Common Good - meta_keywords: - type: array - description: | - Comma-separated list of meta keywords to include in the HTML. - items: - type: string - example: 'modern, clean, contemporary' - meta_description: - maxLength: 65535 - minLength: 0 - type: string - description: | - A meta description to include. - example: Common Good is a modern brand. - search_keywords: - maxLength: 65535 - minLength: 0 - type: string - description: | - A comma-separated list of keywords that can be used to locate this brand. - example: 'kitchen, laundry, cart, storage' - image_url: - type: string - description: | - Image URL used for this category on the storefront. Images can be uploaded via form file post to `/brands/{brandId}/image`, or by providing a publicly accessible URL in this field. - example: 'https://cdn8.bigcommerce.com/s-12345/product_images/k/your-image-name.png' - x-url: true - custom_url: - $ref: '#/components/schemas/customUrl_Full' - description: Common Brand properties. - x-internal: false - productVariant_Base: - title: productVariant_Base - type: object - properties: - cost_price: - minimum: 0 - type: number - description: The cost price of the variant. Not affected by Price List prices. - format: double - nullable: true - price: - minimum: 0 - type: number - description: 'This variant’s base price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is `null`, the product’s default price (set in the Product resource’s `price` field) will be used as the base price.' - format: double - nullable: true - sale_price: - minimum: 0 - type: number - description: 'This variant’s sale price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s sale price (set in the Product resource’s `price` field) will be used as the sale price.' - format: double - nullable: true - retail_price: - minimum: 0 - type: number - description: 'This variant’s retail price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s retail price (set in the Product resource’s `price` field) will be used as the retail price.' - format: double - nullable: true - weight: - minimum: 0 - type: number - description: 'This variant’s base weight on the storefront. If this value is null, the product’s default weight (set in the Product resource’s weight field) will be used as the base weight.' - format: double - nullable: true - width: - minimum: 0 - type: number - description: | - Width of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default width (set in the Product resource's `width` field) will be used as the base width. - format: double - nullable: true - height: - minimum: 0 - type: number - description: | - Height of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default height (set in the Product resource's `height` field) will be used as the base height. - format: double - nullable: true - depth: - minimum: 0 - type: number - description: | - Depth of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default depth (set in the Product resource's `depth` field) will be used as the base depth. - format: double - nullable: true - is_free_shipping: - type: boolean - description: | - Flag used to indicate whether the variant has free shipping. If `true`, the shipping cost for the variant will be zero. - fixed_cost_shipping_price: - minimum: 0 - type: number - description: | - A fixed shipping cost for the variant. If defined, this value will be used during checkout instead of normal shipping-cost calculation. - format: double - nullable: true - purchasing_disabled: - type: boolean - description: 'If `true`, this variant will not be purchasable on the storefront.' - purchasing_disabled_message: - maxLength: 255 - minLength: 0 - type: string - description: 'If `purchasing_disabled` is `true`, this message should show on the storefront when the variant is selected.' - upc: - type: string - description: The UPC code used in feeds for shopping comparison sites and external channel integrations. - nullable: true - inventory_level: - type: integer - description: 'Inventory level for the variant, which is used when the product’s inventory_tracking is set to `variant`.' - nullable: true - inventory_warning_level: - type: integer - description: 'When the variant hits this inventory level, it is considered low stock.' - nullable: true - bin_picking_number: - maxLength: 255 - minLength: 0 - type: string - description: Identifies where in a warehouse the variant is located. - nullable: true - mpn: - type: string - description: The Manufacturer Part Number (MPN) for the variant. - gtin: - type: string - example: '012345678905' - description: Common Variant properties. - x-internal: false - x-examples: - example-1: - cost_price: 0 - price: 0 - sale_price: 0 - retail_price: 0 - weight: 0 - width: 0 - height: 0 - depth: 0 - is_free_shipping: true - fixed_cost_shipping_price: 0 - purchasing_disabled: true - purchasing_disabled_message: string - upc: string - inventory_level: 0 - inventory_warning_level: 0 - bin_picking_number: string - mpn: string - gtin: '012345678905' - productVariant_Full: - title: productVariant_Full - allOf: - - $ref: '#/components/schemas/productVariant_Base' - - type: object - properties: - id: - type: integer - product_id: - type: integer - sku: - type: string - sku_id: - type: integer - description: Read-only reference to v2 API's SKU ID. Null if it is a base variant. - nullable: true - option_values: - type: array - description: Array of option and option values IDs that make up this variant. Will be empty if the variant is the product's base variant. - items: - $ref: '#/components/schemas/productVariantOptionValue_Full' - calculated_price: - type: number - description: | - The price of the variant as seen on the storefront. This price takes into account `sale_price` and any price adjustment rules that are applicable to this variant. - format: double - calculated_weight: - type: number - x-internal: false - description: '' - x-examples: - example-1: - cost_price: 0 - price: 0 - sale_price: 0 - retail_price: 0 - weight: 0 - width: 0 - height: 0 - depth: 0 - is_free_shipping: true - fixed_cost_shipping_price: 0 - purchasing_disabled: true - purchasing_disabled_message: string - upc: string - inventory_level: 0 - inventory_warning_level: 0 - bin_picking_number: string - mpn: string - gtin: '012345678905' - id: 0 - product_id: 0 - sku: string - sku_id: 0 - option_values: - - option_display_name: Color - label: Beige - id: 146 - option_id: 151 - calculated_price: 0 - calculated_weight: 0 - productVariant_Post: - title: productVariant_Post - description: | - The model for a POST to create variants on a product. - allOf: - - title: Variant Base - type: object - properties: - cost_price: - minimum: 0 - type: number - description: The cost price of the variant. Not affected by Price List prices. - format: double - nullable: true - price: - minimum: 0 - type: number - description: 'This variant’s base price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is `null`, the product’s default price (set in the Product resource’s `price` field) will be used as the base price.' - format: double - nullable: true - sale_price: - minimum: 0 - type: number - description: 'This variant’s sale price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s sale price (set in the Product resource’s `price` field) will be used as the sale price.' - format: double - nullable: true - retail_price: - minimum: 0 - type: number - description: 'This variant’s retail price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s retail price (set in the Product resource’s `price` field) will be used as the retail price.' - format: double - nullable: true - weight: - minimum: 0 - type: number - description: 'This variant’s base weight on the storefront. If this value is null, the product’s default weight (set in the Product resource’s weight field) will be used as the base weight.' - format: double - nullable: true - width: - minimum: 0 - type: number - description: | - Width of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default width (set in the Product resource's `width` field) will be used as the base width. - format: double - nullable: true - height: - minimum: 0 - type: number - description: | - Height of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default height (set in the Product resource's `height` field) will be used as the base height. - format: double - nullable: true - depth: - minimum: 0 - type: number - description: | - Depth of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default depth (set in the Product resource's `depth` field) will be used as the base depth. - format: double - nullable: true - is_free_shipping: - type: boolean - description: | - Flag used to indicate whether the variant has free shipping. If `true`, the shipping cost for the variant will be zero. - fixed_cost_shipping_price: - minimum: 0 - type: number - description: | - A fixed shipping cost for the variant. If defined, this value will be used during checkout instead of normal shipping-cost calculation. - format: double - nullable: true - purchasing_disabled: - type: boolean - description: 'If `true`, this variant will not be purchasable on the storefront.' - purchasing_disabled_message: - maxLength: 255 - minLength: 0 - type: string - description: 'If `purchasing_disabled` is `true`, this message should show on the storefront when the variant is selected.' - upc: - type: string - description: The UPC code used in feeds for shopping comparison sites and external channel integrations. - nullable: true - inventory_level: - type: integer - description: 'Inventory level for the variant, which is used when the product’s inventory_tracking is set to `variant`.' - nullable: true - inventory_warning_level: - type: integer - description: 'When the variant hits this inventory level, it is considered low stock.' - nullable: true - bin_picking_number: - maxLength: 255 - minLength: 0 - type: string - description: Identifies where in a warehouse the variant is located. - nullable: true - image_url: - type: string - description: Publicly available image url - gtin: - type: string - description: Global Trade Item Number - example: '012345678905' - mpn: - type: string - description: Manufacturer Part Number - example: HV-HM02 - description: Common Variant properties. - - type: object - properties: - product_id: - type: integer - x-required: - - post - sku: - maxLength: 255 - minLength: 1 - type: string - x-required: - - post - option_values: - type: array - description: Array of option and option values IDs that make up this variant. Will be empty if the variant is the product's base variant. - items: - $ref: '#/components/schemas/productVariantOptionValue_Full' - x-required: - - post - x-internal: false - variantCollection_Put: - title: variantCollection_Put - type: array - items: - $ref: '#/components/schemas/productVariant_Full' - x-internal: false - variant_Put: - title: variant_Put - description: | - The model for a PUT to update variants on a product. - allOf: - - title: Variant Base - type: object - properties: - cost_price: - minimum: 0 - type: number - description: The cost price of the variant. Not affected by Price List prices. - format: double - nullable: true - price: - minimum: 0 - type: number - description: 'This variant’s base price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is `null`, the product’s default price (set in the Product resource’s `price` field) will be used as the base price.' - format: double - nullable: true - sale_price: - minimum: 0 - type: number - description: 'This variant’s sale price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s sale price (set in the Product resource’s `price` field) will be used as the sale price.' - format: double - nullable: true - retail_price: - minimum: 0 - type: number - description: 'This variant’s retail price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s retail price (set in the Product resource’s `price` field) will be used as the retail price.' - format: double - nullable: true - weight: - minimum: 0 - type: number - description: 'This variant’s base weight on the storefront. If this value is null, the product’s default weight (set in the Product resource’s weight field) will be used as the base weight.' - format: double - nullable: true - width: - minimum: 0 - type: number - description: | - Width of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default width (set in the Product resource's `width` field) will be used as the base width. - format: double - nullable: true - height: - minimum: 0 - type: number - description: | - Height of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default height (set in the Product resource's `height` field) will be used as the base height. - format: double - nullable: true - depth: - minimum: 0 - type: number - description: | - Depth of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default depth (set in the Product resource's `depth` field) will be used as the base depth. - format: double - nullable: true - is_free_shipping: - type: boolean - description: | - Flag used to indicate whether the variant has free shipping. If `true`, the shipping cost for the variant will be zero. - fixed_cost_shipping_price: - minimum: 0 - type: number - description: | - A fixed shipping cost for the variant. If defined, this value will be used during checkout instead of normal shipping-cost calculation. - format: double - nullable: true - purchasing_disabled: - type: boolean - description: 'If `true`, this variant will not be purchasable on the storefront.' - purchasing_disabled_message: - maxLength: 255 - minLength: 0 - type: string - description: 'If `purchasing_disabled` is `true`, this message should show on the storefront when the variant is selected.' - upc: - type: string - description: The UPC code used in feeds for shopping comparison sites and external channel integrations. - nullable: true - inventory_level: - type: integer - description: 'Inventory level for the variant, which is used when the product’s inventory_tracking is set to `variant`.' - nullable: true - inventory_warning_level: - type: integer - description: 'When the variant hits this inventory level, it is considered low stock.' - nullable: true - bin_picking_number: - maxLength: 255 - minLength: 0 - type: string - description: Identifies where in a warehouse the variant is located. - nullable: true - description: Common Variant properties. - - type: object - properties: - id: - type: integer - x-required: - - put - x-internal: false - productVariant_Post_Product: - title: productVariant_Post_Product - description: | - The model for a POST to create variants on a product. - allOf: - - $ref: '#/components/schemas/productVariant_Base' - - type: object - properties: - sku: - maxLength: 255 - minLength: 1 - type: string - x-required: - - post - option_values: - type: array - items: - title: Option Value Product Post - type: object - description: The model for a POST to create option values on a product. - allOf: - - title: Option Value Product Base - type: object - properties: - option_display_name: - maxLength: 255 - minLength: 1 - type: string - description: | - The name of the option. - example: Color - x-required: - - post - label: - maxLength: 255 - minLength: 1 - type: string - description: | - The label of the option value. - example: Beige - x-required: - - post - description: Common Option Value Product properties. - x-required: - - post - x-internal: false - productVariant_Put_Product: - title: productVariant_Put_Product - type: object - properties: - cost_price: - minimum: 0 - type: number - description: The cost price of the variant. Not affected by Price List prices. - format: double - nullable: true - price: - minimum: 0 - type: number - description: 'This variant’s base price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is `null`, the product’s default price (set in the Product resource’s `price` field) will be used as the base price.' - format: double - nullable: true - sale_price: - minimum: 0 - type: number - description: 'This variant’s sale price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s sale price (set in the Product resource’s `price` field) will be used as the sale price.' - format: double - nullable: true - retail_price: - minimum: 0 - type: number - description: 'This variant’s retail price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s retail price (set in the Product resource’s `price` field) will be used as the retail price.' - format: double - nullable: true - weight: - minimum: 0 - type: number - description: 'This variant’s base weight on the storefront. If this value is null, the product’s default weight (set in the Product resource’s weight field) will be used as the base weight.' - format: double - nullable: true - width: - minimum: 0 - type: number - description: | - Width of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default width (set in the Product resource's `width` field) will be used as the base width. - format: double - nullable: true - height: - minimum: 0 - type: number - description: | - Height of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default height (set in the Product resource's `height` field) will be used as the base height. - format: double - nullable: true - depth: - minimum: 0 - type: number - description: | - Depth of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default depth (set in the Product resource's `depth` field) will be used as the base depth. - format: double - nullable: true - is_free_shipping: - type: boolean - description: | - Flag used to indicate whether the variant has free shipping. If `true`, the shipping cost for the variant will be zero. - fixed_cost_shipping_price: - minimum: 0 - type: number - description: | - A fixed shipping cost for the variant. If defined, this value will be used during checkout instead of normal shipping-cost calculation. - format: double - nullable: true - purchasing_disabled: - type: boolean - description: 'If `true`, this variant will not be purchasable on the storefront.' - purchasing_disabled_message: - maxLength: 255 - minLength: 0 - type: string - description: 'If `purchasing_disabled` is `true`, this message should show on the storefront when the variant is selected.' - upc: - type: string - description: The UPC code used in feeds for shopping comparison sites and external channel integrations. - nullable: true - inventory_level: - type: integer - description: 'Inventory level for the variant, which is used when the product’s inventory_tracking is set to `variant`.' - nullable: true - inventory_warning_level: - type: integer - description: 'When the variant hits this inventory level, it is considered low stock.' - nullable: true - bin_picking_number: - maxLength: 255 - minLength: 0 - type: string - description: Identifies where in a warehouse the variant is located. - nullable: true - product_id: - type: integer - sku: - maxLength: 255 - minLength: 1 - type: string - description: | - The model for a PUT to update variants on a product. - x-internal: false - productVariantOptionValue_Full: - title: productVariantOptionValue_Full - allOf: - - type: object - properties: - option_display_name: - maxLength: 255 - minLength: 1 - type: string - description: | - The name of the option. - example: Color - x-required: - - post - label: - maxLength: 255 - minLength: 1 - type: string - description: | - The label of the option value. - example: Beige - x-required: - - post - - $ref: '#/components/schemas/productVariantOptionValue_Base' - x-internal: false - productOptionValue_Post_Product: - title: productOptionValue_Post_Product - description: The model for a POST to create option values on a product. - allOf: - - title: Option Value Product Base - type: object - properties: - option_display_name: - maxLength: 255 - minLength: 1 - type: string - description: | - The name of the option. - example: Color - x-required: - - post - label: - maxLength: 255 - minLength: 1 - type: string - description: | - The label of the option value. - example: Beige - x-required: - - post - description: Common Option Value Product properties. - x-internal: false - productVariantOptionValue_Base: - title: productVariantOptionValue_Base - type: object - properties: - id: - type: integer - description: '`option_value` ID.' - example: 146 - option_id: - type: integer - description: '`option` ID.' - example: 151 - description: Common Product Variant Option properties. - x-internal: false - productVariantOptionValue_Post: - title: productVariantOptionValue_Post - type: object - properties: - id: - type: integer - x-required: - - post - option_id: - type: integer - x-required: - - post - description: The model for a POST to create option values on a variant. - x-internal: false - resp_productOptionValue: - title: resp_productOptionValue - type: object - properties: - data: - $ref: '#/components/schemas/productOptionOptionValue_Full' - meta: - title: Meta - type: object - properties: - 'null': - type: string - description: Empty meta object; may be used later. - x-internal: false - productOptionOptionValue_Base: - title: productOptionOptionValue_Base - required: - - label - - sort_order - type: object - properties: - is_default: - type: boolean - description: | - The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. - example: false - label: - type: string - description: | - The text display identifying the value on the storefront. Required in a /POST. - example: Green - x-required: - - post - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the value will be displayed on the product page. Required in a /POST. - example: 0 - x-required: - - post - value_data: - type: object - properties: {} - description: | - Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. If no data is available, returns `null`. - nullable: true - description: Common Product Option `option_value` properties. - x-internal: false - productOptionOptionValue_Full: - title: productOptionOptionValue_Full - description: Product Option `option_value`. - allOf: - - $ref: '#/components/schemas/productOptionOptionValue_Base' - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the value; increments sequentially. - x-internal: false - productOptionValue_Post: - title: productOptionValue_Post - description: The model for a POST to create option values on a product. - allOf: - - title: Option Value Base - required: - - label - - sort_order - type: object - properties: - is_default: - type: boolean - description: | - The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. - example: false - label: - type: string - description: | - The text display identifying the value on the storefront. Required in a /POST. - example: Green - x-required: - - post - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the value will be displayed on the product page. Required in a /POST. - example: 0 - x-required: - - post - value_data: - type: object - properties: {} - description: | - Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. - description: Common Option Value properties. - x-internal: false - productOptionValue_Put: - title: productOptionValue_Put - description: The model for a PUT to update option values on a product. - allOf: - - title: Option Value Base - required: - - label - - sort_order - type: object - properties: - is_default: - type: boolean - description: | - The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. - example: false - label: - type: string - description: | - The text display identifying the value on the storefront. Required in a /POST. - example: Green - x-required: - - post - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the value will be displayed on the product page. Required in a /POST. - example: 0 - x-required: - - post - value_data: - type: object - properties: {} - description: | - Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. - description: Common Option Value properties. - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the value; increments sequentially. - x-required: - - put - x-internal: false - productImage_Base: - title: productImage_Base - type: object - properties: - image_file: - type: string - description: | - The local path to the original image file uploaded to BigCommerce. Limit of 1MB per file. - is_thumbnail: - type: boolean - description: | - Flag for identifying whether the image is used as the product's thumbnail. - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the image will be displayed on the product page. Higher integers give the image a lower priority. When updating, if the image is given a lower priority, all images with a `sort_order` the same as or greater than the image's new `sort_order` value will have their `sort_order`s reordered. - description: - type: string - description: | - The description for the image. - image_url: - type: string - description: 'Must be a fully qualified URL path, including protocol. Limit of 8MB per file.' - description: Common ProductImage properties. - x-internal: false - productImage_Post: - title: productImage_Post - description: The model for a POST to create an image on a product. - allOf: - - title: Product Image Base - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the image; increments sequentially. - product_id: - type: integer - description: | - The unique numeric identifier for the product with which the image is associated. - image_file: - type: string - description: | - The local path to the original image file uploaded to BigCommerce. - url_zoom: - type: string - description: | - The zoom URL for this image. By default, this is used as the zoom image on product pages when zoom images are enabled. - url_standard: - type: string - description: | - The standard URL for this image. By default, this is used for product-page images. - url_thumbnail: - type: string - description: | - The thumbnail URL for this image. By default, this is the image size used on the category page and in side panels. - url_tiny: - type: string - description: | - The tiny URL for this image. By default, this is the image size used for thumbnails beneath the product image on a product page. - date_modified: - type: string - description: | - The date on which the product image was modified. - format: date-time - is_thumbnail: - type: boolean - description: | - Flag for identifying whether the image is used as the product's thumbnail. - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the image will be displayed on the product page. Higher integers give the image a lower priority. When updating, if the image is given a lower priority, all images with a `sort_order` the same as or greater than the image's new `sort_order` value will have their `sort_order`s reordered. - description: - type: string - description: | - The description for the image. - description: Common ProductImage properties. - - type: object - properties: - image_url: - type: string - description: | - Must be a fully qualified URL path, including protocol. Limit of 8MB per file. - image_file: - type: string - description: | - Must be sent as a multipart/form-data field in the request body. - x-internal: false - productImage_Put: - title: productImage_Put - description: The model for a PUT to update applicable Product Image fields. - allOf: - - title: Product Image Base - type: object - properties: - product_id: - type: integer - description: | - The unique numeric identifier for the product with which the image is associated. - url_zoom: - type: string - description: | - The zoom URL for this image. By default, this is used as the zoom image on product pages when zoom images are enabled. - url_standard: - type: string - description: | - The standard URL for this image. By default, this is used for product-page images. - url_thumbnail: - type: string - description: | - The thumbnail URL for this image. By default, this is the image size used on the category page and in side panels. - url_tiny: - type: string - description: | - The tiny URL for this image. By default, this is the image size used for thumbnails beneath the product image on a product page. - description: Common ProductImage properties. - - $ref: '#/components/schemas/productImage_Base' - x-internal: false - productVideo_Base: - title: productVideo_Base - type: object - description: | - The model for a POST to create a video on a product. - x-internal: false - properties: - title: - type: string - maxLength: 255 - minLength: 0 - description: | - The title for the video. If left blank, this will be filled in according to data on a host site. - example: Writing Great Documentation - description: - type: string - description: | - The description for the video. If left blank, this will be filled in according to data on a host site. - example: A video about documenation - sort_order: - type: integer - maximum: 2147483647 - minimum: -2147483648 - description: | - The order in which the video will be displayed on the product page. Higher integers give the video a lower priority. When updating, if the video is given a lower priority, all videos with a `sort_order` the same as or greater than the video's new `sort_order` value will have their `sort_order`s reordered. - example: 1 - type: - type: string - description: | - The video type (a short name of a host site). - enum: - - youtube - video_id: - type: string - description: The ID of the video on a host site. - example: z3fRu9pkuXE - productVideo_Full: - title: productVideo_Full - description: | - A product video model. - allOf: - - $ref: '#/components/schemas/productVideo_Base' - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the product video; increments sequentially. - product_id: - type: integer - description: | - The unique numeric identifier for the product with which the image is associated. - length: - type: string - description: | - Length of the video. This will be filled in according to data on a host site. - x-internal: false - productVideo_Post: - title: productVideo_Post - description: | - The model for a POST to create a video on a product. - allOf: - - $ref: '#/components/schemas/productVideo_Base' - x-internal: false - productVideo_Put: - title: productVideo_Put - description: | - The model for a PUT to update a video on a product. - allOf: - - $ref: '#/components/schemas/productVideo_Base' - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the product video; increments sequentially. - x-required: - - put - x-internal: false - productReview_Base: - title: productReview_Base - required: - - date_reviewed - - title - type: object - properties: - title: - maxLength: 255 - minLength: 0 - type: string - description: |- - The title for the product review. - Required in /POST. - text: - type: string - description: | - The text for the product review. - status: - type: string - description: | - The status of the product review. Must be one of `approved`, `disapproved` or `pending`. - rating: - type: integer - description: 'The rating of the product review. Must be one of 0, 1, 2, 3, 4, 5.' - email: - type: string - description: 'The email of the reviewer. Must be a valid email, or an empty string.' - name: - maxLength: 255 - minLength: 0 - type: string - description: The name of the reviewer. - date_reviewed: - type: string - description: | - Date the product was reviewed. Required in /POST. - format: date-time - x-internal: false - productReview_Full: - title: productReview_Full - description: | - A product review model. - allOf: - - $ref: '#/components/schemas/productReview_Base' - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the product review; increments sequentially. - product_id: - type: integer - description: | - The unique numeric identifier for the product with which the review is associated. - date_created: - type: string - description: | - Date the product review was created. - format: date-time - date_modified: - type: string - description: | - Date the product review was modified. - format: date-time - x-internal: false - productReview_Post: - title: productReview_Post - description: | - The model for a POST to create a product review. - allOf: - - title: Product Review Base - required: - - date_reviewed - - title - type: object - properties: - title: - maxLength: 255 - minLength: 0 - type: string - description: |- - The title for the product review. - Required in /POST. - text: - type: string - description: | - The text for the product review. - status: - type: string - description: | - The status of the product review. Must be one of `approved`, `disapproved` or `pending`. - rating: - type: integer - description: 'The rating of the product review. Must be one of 0, 1, 2, 3, 4, 5.' - email: - type: string - description: 'The email of the reviewer. Must be a valid email, or an empty string.' - name: - maxLength: 255 - minLength: 0 - type: string - description: The name of the reviewer. - date_reviewed: - type: string - description: | - Date the product was reviewed. Required in /POST. - format: date-time - x-internal: false - productReview_Put: - title: productReview_Put - description: | - The model for a PUT to update a product review. - allOf: - - title: Product Review Base - required: - - date_reviewed - - title - type: object - properties: - title: - maxLength: 255 - minLength: 0 - type: string - description: |- - The title for the product review. - Required in /POST. - text: - type: string - description: | - The text for the product review. - status: - type: string - description: | - The status of the product review. Must be one of `approved`, `disapproved` or `pending`. - rating: - type: integer - description: 'The rating of the product review. Must be one of 0, 1, 2, 3, 4, 5.' - email: - type: string - description: 'The email of the reviewer. Must be a valid email, or an empty string.' - name: - maxLength: 255 - minLength: 0 - type: string - description: The name of the reviewer. - date_reviewed: - type: string - description: | - Date the product was reviewed. Required in /POST. - format: date-time - x-internal: false - resp_productImage: - title: resp_productImage - type: object - properties: - data: - $ref: '#/components/schemas/productImage_Full' - meta: - title: Meta - type: object - properties: {} - description: Empty meta object; may be used later. - description: |- - Image Response returns for: - * Create Variant Image - * Create Modifier Image - * Create Category Image - * Create Brand Image - x-internal: false - resourceImage_Full: - title: resourceImage_Full - type: object - properties: - image_url: - type: string - description: | - A public URL for a GIF, JPEG, or PNG image. Limit of 8MB per file. - description: 'An object containing a publicly accessible image URL, or a form post that contains an image file.' - x-internal: false - product_Post: - title: product_Post - description: The model for a POST to create a product. - allOf: - - $ref: '#/components/schemas/product_Base' - - type: object - properties: - variants: - type: array - items: - $ref: '#/components/schemas/productVariant_Post_Product' - x-internal: false - product_Put: - title: product_Put - description: The model for a PUT to update a product. - allOf: - - $ref: '#/components/schemas/product_Base' - - type: object - properties: - variants: - type: array - items: - $ref: '#/components/schemas/productVariant_Put_Product' - x-internal: false - catalogSummary_Full: - title: catalogSummary_Full - type: object - properties: - inventory_count: - type: integer - description: | - A count of all inventory items in the catalog. - example: 2000 - inventory_value: - type: number - description: | - Total value of store's inventory. - format: double - example: 267000 - primary_category_id: - type: integer - description: | - ID of the category containing the most products. - example: 23 - primary_category_name: - type: string - description: | - Name of the category containing the most products. - example: Shop All - variant_count: - type: integer - description: Total number of variants - example: 46 - highest_variant_price: - type: number - description: Highest priced variant - format: double - example: 249 - average_variant_price: - type: number - description: Average price of all variants - format: double - example: 83.07978261 - lowest_variant_price: - type: string - description: Lowest priced variant in the store - example: '7' - oldest_variant_date: - type: string - example: '2018-08-15T00:00:00+00:00' - newest_variant_date: - type: string - example: '2018-08-16T00:00:00+00:00' - description: Catalog Summary object describes a lightweight summary of the catalog. - x-internal: false - metafield_Base: - title: metafield_Base - type: object - description: 'Metafield for products, categories, variants, and brands; the max number of metafields allowed on each is 50. For more information, see [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center.' - x-internal: false - properties: - key: - maxLength: 64 - minLength: 1 - type: string - description: | - The name of the field, for example: `location_id`, `color`. Required for POST. - example: Location - x-required: - - post - value: - maxLength: 65535 - minLength: 1 - type: string - description: | - The value of the field, for example: `1`, `blue`. Required for POST. - example: 4HG - x-required: - - post - namespace: - maxLength: 64 - minLength: 1 - type: string - description: | - Namespace for the metafield, for organizational purposes. This is set by the developer. Required for POST. - example: Warehouse Locations - x-required: - - post - permission_set: - type: string - description: |- - Determines the visibility and writeability of the field by other API consumers. - - |Value|Description - |-|-| - |`app_only`|Private to the app that owns the field| - |`read`|Visible to other API consumers| - |`write`|Open for reading and writing by other API consumers| - |`read_and_sf_access`|Visible to other API consumers, including on storefront| - |`write_and_sf_access`|Open for reading and writing by other API consumers, including on storefront| - enum: - - app_only - - read - - write - - read_and_sf_access - - write_and_sf_access - description: - maxLength: 255 - minLength: 0 - type: string - description: | - Description for the metafields. - example: Location in the warehouse - required: - - permission_set - - namespace - - key - - value - complexRule_Base: - title: complexRule_Base - type: object - properties: - id: - type: integer - description: |- - The unique numeric ID of the rule; increments sequentially. - Read-Only - example: 5 - product_id: - type: integer - description: | - The unique numeric ID of the product with which the rule is associated; increments sequentially. - nullable: true - example: 67 - x-required: - - post - - put - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The priority to give this rule when making adjustments to the product properties. - example: 0 - enabled: - type: boolean - description: | - Flag for determining whether the rule is to be used when adjusting a product's price, weight, image, or availabilty. - example: true - stop: - type: boolean - description: | - Flag for determining whether other rules should not be applied after this rule has been applied. - purchasing_disabled: - type: boolean - description: | - Flag for determining whether the rule should disable purchasing of a product when the conditions are applied. - purchasing_disabled_message: - maxLength: 255 - minLength: 0 - type: string - description: | - Message displayed on the storefront when a rule disables the purchasing of a product. - example: This product is not available at this time. - purchasing_hidden: - type: boolean - description: | - Flag for determining whether the rule should hide purchasing of a product when the conditions are applied. - image_url: - type: string - description: | - The URL for an image displayed on the storefront when the conditions are applied. Limit of 8MB per file. - example: 'https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png' - price_adjuster: - $ref: '#/components/schemas/adjuster_Full' - weight_adjuster: - $ref: '#/components/schemas/adjuster_Full' - conditions: - type: array - items: - $ref: '#/components/schemas/complexRuleConditionBase' - description: Common ComplexRule properties. - x-internal: false - productCustomField_Base: - title: productCustomField_Base - required: - - name - - value - type: object - properties: - id: - minimum: 1 - type: integer - description: |- - The unique numeric ID of the custom field; increments sequentially. - Read-Only - example: 6 - name: - maxLength: 250 - minLength: 1 - type: string - description: | - The name of the field, shown on the storefront, orders, etc. Required for /POST - example: ISBN - x-required: - - post - value: - maxLength: 250 - minLength: 1 - type: string - description: | - The name of the field, shown on the storefront, orders, etc. Required for /POST - example: '1234567890123' - x-required: - - post - description: 'Gets custom fields associated with a product. These allow you to specify additional information that will appear on the product’s page, such as a book’s ISBN or a DVD’s release date.' - x-internal: false - productCustomField_Post: - title: productCustomField_Post - description: The model for a POST to create a custom field on a product. - allOf: - - title: Custom Field - required: - - name - - value - type: object - properties: - id: - minimum: 1 - type: integer - description: |- - The unique numeric ID of the custom field; increments sequentially. - Read-Only - example: 6 - name: - maxLength: 250 - minLength: 1 - type: string - description: | - The name of the field, shown on the storefront, orders, etc. Required for /POST - example: ISBN - x-required: - - post - value: - maxLength: 250 - minLength: 1 - type: string - description: | - The name of the field, shown on the storefront, orders, etc. Required for /POST - example: '1234567890123' - x-required: - - post - description: 'Gets custom fields associated with a product. These allow you to specify additional information that will appear on the product’s page, such as a book’s ISBN or a DVD’s release date.' - x-internal: false - productCustomField_Put: - title: productCustomField_Put - required: - - name - - value - type: object - properties: - id: - minimum: 1 - type: integer - description: |- - The unique numeric ID of the custom field; increments sequentially. Required to update existing custom field in /PUT request. - Read-Only - example: 6 - name: - maxLength: 250 - minLength: 1 - type: string - description: | - The name of the field, shown on the storefront, orders, etc. Required for /POST - example: ISBN - x-required: - - post - value: - maxLength: 250 - minLength: 1 - type: string - description: | - The name of the field, shown on the storefront, orders, etc. Required for /POST - example: '1234567890123' - x-required: - - post - description: The model for a PUT to update a custom field on a product. - x-internal: false - complexRuleConditionBase: - title: complexRuleConditionBase - required: - - modifier_id - - modifier_value_id - - variant_id - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the rule condition; increments sequentially. Read-Only - nullable: true - example: 3 - rule_id: - type: integer - description: |- - The unique numeric ID of the rule with which the condition is associated. - Read-Only - nullable: true - example: 4 - modifier_id: - type: integer - description: |- - The unique numeric ID of the modifier with which the rule condition is associated. - Required in /POST. - nullable: true - example: 55 - modifier_value_id: - type: integer - description: |- - The unique numeric ID of the modifier value with which the rule condition is associated. - Required in /POST. - nullable: true - example: 256 - variant_id: - type: integer - description: |- - The unique numeric ID of the variant with which the rule condition is associated. - Required in /POST. - nullable: true - example: 1 - combination_id: - type: integer - description: | - (READ-ONLY:) The unique numeric ID of the SKU (v2 API), or Combination, with which the rule condition is associated. This is to maintain cross-compatibility between v2 and v3. - description: 'Complex rules may return with conditions that apply to one or more variants, or with a single modifier value (if the rules were created using the v2 API or the control panel). Complex rules created or updated in the v3 API must have conditions that either reference multiple `modifier_value_id`’s, or else reference a `modifier_value_id` and a `variant_id`.' - x-internal: false - customUrl_Full: - title: customUrl_Full - type: object - properties: - url: - maxLength: 255 - minLength: 0 - type: string - description: | - Product URL on the storefront. - x-required: - - post - - put - x-url: true - is_customized: - type: boolean - description: | - Returns `true` if the URL has been changed from its default state (the auto-assigned URL that BigCommerce provides). - x-required: - - post - - put - description: The custom URL for the product on the storefront. - x-internal: false - bulkPricingRule_Full: - title: bulkPricingRule_Full - required: - - amount - - quantity_max - - quantity_min - - type - type: object - properties: - quantity_min: - minimum: 0 - type: integer - description: | - The minimum inclusive quantity of a product to satisfy this rule. Must be greater than or equal to zero. - Required in /POST. - example: 10 - x-required: - - post - quantity_max: - minimum: 0 - type: integer - description: |- - The maximum inclusive quantity of a product to satisfy this rule. Must be greater than the `quantity_min` value – unless this field has a value of 0 (zero), in which case there will be no maximum bound for this rule. - Required in /POST. - example: 50 - x-required: - - post - type: - type: string - description: |- - The type of adjustment that is made. Values: `price` - the adjustment amount per product; `percent` - the adjustment as a percentage of the original price; `fixed` - the adjusted absolute price of the product. - Required in /POST. - example: price - enum: - - price - - percent - - fixed - x-required: - - post - amount: - type: integer - description: |- - The discount can be a fixed dollar amount or a percentage. For a fixed dollar amount enter it as an integer and the response will return as an integer. For percentage enter the amount as the percentage divided by 100 using string format. For example 10% percent would be “.10”. The response will return as an integer. - Required in /POST. - example: 10 - description: Common Bulk Pricing Rule properties - x-internal: false - productOptionConfig_Full: - title: productOptionConfig_Full - type: object - properties: - default_value: - type: string - description: | - (date, text, multi_line_text, numbers_only_text) The default value. Shown on a date option as an ISO-8601–formatted string, or on a text option as a string. - checked_by_default: - type: boolean - description: | - (checkbox) Flag for setting the checkbox to be checked by default. - checkbox_label: - type: string - description: | - (checkbox) Label displayed for the checkbox option. - date_limited: - type: boolean - description: | - (date) Flag to limit the dates allowed to be entered on a date option. - date_limit_mode: - type: string - description: | - (date) The type of limit that is allowed to be entered on a date option. - example: range - enum: - - earliest - - range - - latest - date_earliest_value: - type: string - description: | - (date) The earliest date allowed to be entered on the date option, as an ISO-8601 formatted string. - format: date - date_latest_value: - type: string - description: | - (date) The latest date allowed to be entered on the date option, as an ISO-8601 formatted string. - format: date - file_types_mode: - type: string - description: | - (file) The kind of restriction on the file types that can be uploaded with a file upload option. Values: `specific` - restricts uploads to particular file types; `all` - allows all file types. - example: specific - enum: - - specific - - all - file_types_supported: - type: array - description: | - (file) The type of files allowed to be uploaded if the `file_type_option` is set to `specific`. Values: - `images` - Allows upload of image MIME types (`bmp`, `gif`, `jpg`, `jpeg`, `jpe`, `jif`, `jfif`, `jfi`, `png`, `wbmp`, `xbm`, `tiff`). `documents` - Allows upload of document MIME types (`txt`, `pdf`, `rtf`, `doc`, `docx`, `xls`, `xlsx`, `accdb`, `mdb`, `one`, `pps`, `ppsx`, `ppt`, `pptx`, `pub`, `odt`, `ods`, `odp`, `odg`, `odf`). - `other` - Allows file types defined in the `file_types_other` array. - items: - type: string - example: 'images, documents, other' - file_types_other: - type: array - description: | - (file) A list of other file types allowed with the file upload option. - items: - type: string - example: pdf - file_max_size: - type: integer - description: | - (file) The maximum size for a file that can be used with the file upload option. This will still be limited by the server. - example: 5 - text_characters_limited: - type: boolean - description: | - (text, multi_line_text) Flag to validate the length of a text or multi-line text input. - text_min_length: - type: integer - description: | - (text, multi_line_text) The minimum length allowed for a text or multi-line text option. - example: 1 - text_max_length: - type: integer - description: | - (text, multi_line_text) The maximum length allowed for a text or multi line text option. - example: 55 - text_lines_limited: - type: boolean - description: | - (multi_line_text) Flag to validate the maximum number of lines allowed on a multi-line text input. - example: true - text_max_lines: - type: integer - description: | - (multi_line_text) The maximum number of lines allowed on a multi-line text input. - example: 4 - number_limited: - type: boolean - description: | - (numbers_only_text) Flag to limit the value of a number option. - example: true - number_limit_mode: - type: string - description: | - (numbers_only_text) The type of limit on values entered for a number option. - example: lowest - enum: - - lowest - - highest - - range - number_lowest_value: - type: number - description: | - (numbers_only_text) The lowest allowed value for a number option if `number_limited` is true. - example: 100 - number_highest_value: - type: number - description: | - (numbers_only_text) The highest allowed value for a number option if `number_limited` is true. - number_integers_only: - type: boolean - description: | - (numbers_only_text) Flag to limit the input on a number option to whole numbers only. - example: false - product_list_adjusts_inventory: - type: boolean - description: | - (product_list, product_list_with_images) Flag for automatically adjusting inventory on a product included in the list. - product_list_adjusts_pricing: - type: boolean - description: | - (product_list, product_list_with_images) Flag to add the optional product's price to the main product's price. - product_list_shipping_calc: - type: string - description: | - (product_list, product_list_with_images) How to factor the optional product's weight and package dimensions into the shipping quote. Values: `none` - don't adjust; `weight` - use shipping weight only; `package` - use weight and dimensions. - example: weight - enum: - - none - - weight - - package - description: The values for option config can vary based on the Modifier created. - x-internal: false - adjuster_Full: - title: adjuster_Full - type: object - properties: - adjuster: - type: string - description: | - The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - nullable: true - enum: - - relative - - percentage - adjuster_value: - type: number - description: | - The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. - example: 5 - description: Adjuster for Complex Rules. - x-internal: false - resp_variantBatchError: - title: resp_variantBatchError - type: object - properties: - batch_errors: - type: array - items: - title: Error Response - type: object - allOf: - - $ref: '#/components/schemas/error_Base' - - type: object - properties: - errors: - title: Detailed Errors - type: object - properties: {} - additionalProperties: true - description: | - Errors during batch usage for the BigCommerce API. - x-internal: false - metaCollection_open: - title: Response meta - type: object - properties: {} - additionalProperties: true - description: Response metadata. - metaCollection_Full: - title: metaCollection_Full - type: object - properties: - pagination: - $ref: '#/components/schemas/pagination_Full' - description: 'Data about the response, including pagination and collection totals.' - x-internal: false - pagination_Full: - title: pagination_Full - type: object - properties: - total: - type: integer - description: | - Total number of items in the result set. - example: 36 - count: - type: integer - description: | - Total number of items in the collection response. - example: 36 - per_page: - type: integer - description: | - The amount of items returned in the collection per page, controlled by the limit parameter. - example: 50 - current_page: - type: integer - description: | - The page you are currently on within the collection. - example: 1 - total_pages: - type: integer - description: | - The total number of pages in the collection. - example: 1 - links: - type: object - properties: - previous: - type: string - description: | - Link to the previous page returned in the response. - current: - type: string - description: | - Link to the current page returned in the response. - example: '?page=1&limit=50' - next: - type: string - description: | - Link to the next page returned in the response. - description: | - Pagination links for the previous and next parts of the whole collection. - description: 'Data about the response, including pagination and collection totals.' - x-internal: false - metaEmpty_Full: - type: object - title: Response meta - properties: {} - additionalProperties: true - description: Response metadata. - errorResponse_Full: - title: errorResponse_Full - allOf: - - $ref: '#/components/schemas/error_Base' - - type: object - properties: - errors: - $ref: '#/components/schemas/detailedErrors' - x-internal: false - error_Base: - title: error_Base - type: object - properties: - status: - type: integer - description: | - The HTTP status code. - title: - type: string - description: | - The error title describing the particular error. - type: - type: string - instance: - type: string - description: | - Error payload for the BigCommerce API. - x-internal: false - errorMultiStatus: - title: errorMultiStatus - type: object - properties: - status: - type: integer - minLength: 3 - maxLength: 3 - description: 'The [HTTP status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) of the failure or partial success.' - title: - type: string - description: A summary of the failure or partial success. - type: - type: string - description: A BigCommerce-defined error signifier. - errors: - $ref: '#/components/schemas/detailedErrors' - errorNotFound: - title: errorNotFound - type: object - properties: - status: - type: integer - description: | - 404 HTTP status code. - title: - type: string - description: The error title describing the particular error. - type: - type: string - instance: - type: string - description: Error payload for the BigCommerce API. - x-internal: false - giftCertificate_Full: - title: giftCertificate_Full - type: object - properties: - code: - type: string - description: | - The gift-certificate code. - example: MB345 - original_balance: - type: number - description: | - The balance on a gift certificate when it was purchased. - format: float - example: 100 - starting_balance: - type: number - description: | - The balance on a gift certificate at the time of this purchase. - format: float - example: 100 - remaining_balance: - type: number - description: | - The remaining balance on a gift certificate. - format: float - example: 35.42 - status: - type: string - description: | - The status of a gift certificate: `active` - gift certificate is active; `pending` - gift certificate purchase is pending; `disabled` - gift certificate is disabled; `expired` - gift certificate is expired. - enum: - - active - - pending - - disabled - - expired - description: A gift-certificate model. - x-internal: false - errorNoContent: - title: errorNoContent - type: object - properties: - status: - type: integer - description: | - 204 HTTP status code. - title: - type: string - description: The error title describing the situation. - type: - type: string - instance: - type: string - description: No-content response for the BigCommerce API. - x-internal: false - detailedErrors: - title: detailedErrors - description: Each key-value pair describes a failure or partial success case. - type: object - properties: {} - additionalProperties: true - x-internal: false - product_Full: - title: product_Full - allOf: - - type: object - properties: - id: - minimum: 1 - type: integer - description: ID of the product. Read-Only. - readOnly: true - - $ref: '#/components/schemas/product_Base' - - type: object - properties: - date_created: - type: string - description: | - The date on which the product was created. - format: date-time - example: '2018-08-15T14:49:05+00:00' - date_modified: - type: string - description: | - The date on which the product was modified. - format: date-time - example: '2018-08-24T14:41:00+00:00' - base_variant_id: - type: integer - description: The unique identifier of the base variant associated with a simple product. This value is `null` for complex products. - calculated_price: - type: number - description: 'The price of the product as seen on the storefront. It will be equal to the `sale_price`, if set, and the `price` if there is not a `sale_price`.' - format: float - options: - type: array - items: - $ref: '#/components/schemas/productOption_Base' - modifiers: - type: array - items: - $ref: '#/components/schemas/productModifier_Full' - map_price: - type: number - description: Minimum Advertised Price. - option_set_id: - type: integer - description: Indicates that the product is in an Option Set (legacy V2 concept). - option_set_display: - type: string - description: Legacy template setting which controls if the option set shows up to the side of or below the product image and description. - variants: - type: array - items: - $ref: '#/components/schemas/productVariant_Full' - x-internal: false - productImage_Full: - title: productImage_Full - description: Common ProductImage properties. - allOf: - - $ref: '#/components/schemas/productImage_Base' - - title: productImage - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the image; increments sequentially. - product_id: - type: integer - description: | - The unique numeric identifier for the product with which the image is associated. - url_zoom: - type: string - description: | - The zoom URL for this image. By default, this is used as the zoom image on product pages when zoom images are enabled. - url_standard: - type: string - description: | - The standard URL for this image. By default, this is used for product-page images. - url_thumbnail: - type: string - description: | - The thumbnail URL for this image. By default, this is the image size used on the category page and in side panels. - url_tiny: - type: string - description: | - The tiny URL for this image. By default, this is the image size used for thumbnails beneath the product image on a product page. - date_modified: - type: string - description: | - The date on which the product image was modified. - format: date-time - description: Common ProductImage properties. - x-internal: false - product_Put_Collection: - title: product_Put_Collection - description: The model for batch updating products. - x-internal: false - allOf: - - items: - $ref: '#/components/schemas/product_Base' - x-examples: - example-1: - - name: Smith Journal 13 - type: physical - sku: SM-13 - description: '<p><span>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vel metus ac est egestas porta sed quis erat. Integer id nulla massa. Proin vitae enim nisi. Praesent non dignissim nulla. Nulla mattis id massa ac pharetra. Mauris et nisi in dolor aliquam sodales. Aliquam dui nisl, dictum quis leo sit amet, rutrum volutpat metus. Curabitur libero nunc, interdum ac libero non, tristique porttitor metus. Ut non dignissim lorem, in vestibulum leo. Vivamus sodales quis turpis eget.</span></p>' - weight: 0 - width: 0 - depth: 0 - height: 0 - price: 0 - cost_price: 0 - retail_price: 0 - sale_price: 0 - map_price: 0 - tax_class_id: 0 - product_tax_code: string - categories: - - 0 - brand_id: 0 - inventory_level: 0 - inventory_warning_level: 0 - inventory_tracking: none - fixed_cost_shipping_price: 0 - is_free_shipping: true - is_visible: true - is_featured: true - related_products: - - 0 - warranty: string - bin_picking_number: string - layout_file: string - upc: string - search_keywords: string - availability: available - availability_description: string - gift_wrapping_options_type: list - gift_wrapping_options_list: - - 0 - sort_order: -2147483648 - condition: New - is_condition_shown: true - order_quantity_minimum: 0 - order_quantity_maximum: 0 - page_title: string - meta_keywords: - - string - meta_description: string - view_count: 0 - preorder_release_date: '2019-08-24T14:15:22Z' - preorder_message: string - is_preorder_only: true - is_price_hidden: true - price_hidden_label: string - custom_url: - url: string - is_customized: true - open_graph_type: product - open_graph_title: string - open_graph_description: string - open_graph_use_meta_description: true - open_graph_use_product_name: true - open_graph_use_image: true - brand_name or brand_id: Common Good - gtin: string - mpn: string - reviews_rating_sum: 3.2 - reviews_count: 4 - total_sold: 80 - custom_fields: - - id: 6 - name: ISBN - value: '1234567890123' - bulk_pricing_rules: - - id: 0 - quantity_min: 10 - quantity_max: 50 - type: price - amount: 10 - images: - - image_file: string - is_thumbnail: true - sort_order: -2147483648 - description: string - image_url: string - id: 0 - product_id: 0 - url_zoom: string - url_standard: string - url_thumbnail: string - url_tiny: string - date_modified: '2019-08-24T14:15:22Z' - videos: - - title: Writing Great Documentation - description: A video about documenation - sort_order: 1 - type: youtube - video_id: z3fRu9pkuXE - id: 0 - product_id: 0 - length: string - type: array - config_Full: - title: config_Full - type: object - properties: - default_value: - type: string - description: | - (date, text, multi_line_text, numbers_only_text) The default value. Shown on a date option as an ISO-8601–formatted string, or on a text option as a string. - checked_by_default: - type: boolean - description: | - (checkbox) Flag for setting the checkbox to be checked by default. - checkbox_label: - type: string - description: | - (checkbox) Label displayed for the checkbox option. - date_limited: - type: boolean - description: | - (date) Flag to limit the dates allowed to be entered on a date option. - date_limit_mode: - type: string - description: | - (date) The type of limit that is allowed to be entered on a date option. - example: range - enum: - - earliest - - range - - latest - date_earliest_value: - type: string - description: | - (date) The earliest date allowed to be entered on the date option, as an ISO-8601 formatted string. - format: date - date_latest_value: - type: string - description: | - (date) The latest date allowed to be entered on the date option, as an ISO-8601 formatted string. - format: date - file_types_mode: - type: string - description: | - (file) The kind of restriction on the file types that can be uploaded with a file upload option. Values: `specific` - restricts uploads to particular file types; `all` - allows all file types. - example: specific - enum: - - specific - - all - file_types_supported: - type: array - description: | - (file) The type of files allowed to be uploaded if the `file_type_option` is set to `specific`. Values: - `images` - Allows upload of image MIME types (`bmp`, `gif`, `jpg`, `jpeg`, `jpe`, `jif`, `jfif`, `jfi`, `png`, `wbmp`, `xbm`, `tiff`). `documents` - Allows upload of document MIME types (`txt`, `pdf`, `rtf`, `doc`, `docx`, `xls`, `xlsx`, `accdb`, `mdb`, `one`, `pps`, `ppsx`, `ppt`, `pptx`, `pub`, `odt`, `ods`, `odp`, `odg`, `odf`). - `other` - Allows file types defined in the `file_types_other` array. - items: - type: string - example: 'images, documents, other' - file_types_other: - type: array - description: | - (file) A list of other file types allowed with the file upload option. - items: - type: string - example: pdf - file_max_size: - type: integer - description: | - (file) The maximum size for a file that can be used with the file upload option. This will still be limited by the server. - example: 5 - text_characters_limited: - type: boolean - description: | - (text, multi_line_text) Flag to validate the length of a text or multi-line text input. - text_min_length: - type: integer - description: | - (text, multi_line_text) The minimum length allowed for a text or multi-line text option. - example: 1 - text_max_length: - type: integer - description: | - (text, multi_line_text) The maximum length allowed for a text or multi line text option. - example: 55 - text_lines_limited: - type: boolean - description: | - (multi_line_text) Flag to validate the maximum number of lines allowed on a multi-line text input. - example: true - text_max_lines: - type: integer - description: | - (multi_line_text) The maximum number of lines allowed on a multi-line text input. - example: 4 - number_limited: - type: boolean - description: | - (numbers_only_text) Flag to limit the value of a number option. - example: true - number_limit_mode: - type: string - description: | - (numbers_only_text) The type of limit on values entered for a number option. - example: lowest - enum: - - lowest - - highest - - range - number_lowest_value: - type: number - description: | - (numbers_only_text) The lowest allowed value for a number option if `number_limited` is true. - example: 100 - number_highest_value: - type: number - description: | - (numbers_only_text) The highest allowed value for a number option if `number_limited` is true. - number_integers_only: - type: boolean - description: | - (numbers_only_text) Flag to limit the input on a number option to whole numbers only. - example: false - product_list_adjusts_inventory: - type: boolean - description: | - (product_list, product_list_with_images) Flag for automatically adjusting inventory on a product included in the list. - product_list_adjusts_pricing: - type: boolean - description: | - (product_list, product_list_with_images) Flag to add the optional product's price to the main product's price. - product_list_shipping_calc: - type: string - description: | - (product_list, product_list_with_images) How to factor the optional product's weight and package dimensions into the shipping quote. Values: `none` - don't adjust; `weight` - use shipping weight only; `package` - use weight and dimensions. - example: weight - enum: - - none - - weight - - package - description: The values for option config can vary based on the Modifier created. - x-internal: false - adjusters_Full: - title: adjusters_Full - type: object - properties: - price: - $ref: '#/components/schemas/adjuster_Full' - weight: - $ref: '#/components/schemas/adjuster_Full' - image_url: - type: string - description: | - The URL for an image displayed on the storefront when the modifier value is selected.Limit of 8MB per file. - example: 'https://cdn8.bigcommerce.com/s-{{store_hash}}/products/184/images/445/naturalcanvascart2_1024x1024__92347__29648.1534344533.1280.1280.jpg?c=2' - purchasing_disabled: - type: object - properties: - status: - type: boolean - description: | - Flag for whether the modifier value disables purchasing when selected on the storefront. This can be used for temporarily disabling a particular modifier value. - message: - type: string - description: | - The message displayed on the storefront when the purchasing disabled status is `true`. - x-internal: false - variant_Base: - title: variant_Base - type: object - properties: - cost_price: - minimum: 0 - type: number - description: The cost price of the variant. Not affected by Price List prices. - format: double - nullable: true - price: - minimum: 0 - type: number - description: 'This variant’s base price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is `null`, the product’s default price (set in the Product resource’s `price` field) will be used as the base price.' - format: double - nullable: true - sale_price: - minimum: 0 - type: number - description: 'This variant’s sale price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s sale price (set in the Product resource’s `price` field) will be used as the sale price.' - format: double - nullable: true - retail_price: - minimum: 0 - type: number - description: 'This variant’s retail price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s retail price (set in the Product resource’s `price` field) will be used as the retail price.' - format: double - nullable: true - weight: - minimum: 0 - type: number - description: 'This variant’s base weight on the storefront. If this value is null, the product’s default weight (set in the Product resource’s weight field) will be used as the base weight.' - format: double - nullable: true - width: - minimum: 0 - type: number - description: | - Width of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default width (set in the Product resource's `width` field) will be used as the base width. - format: double - nullable: true - height: - minimum: 0 - type: number - description: | - Height of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default height (set in the Product resource's `height` field) will be used as the base height. - format: double - nullable: true - depth: - minimum: 0 - type: number - description: | - Depth of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default depth (set in the Product resource's `depth` field) will be used as the base depth. - format: double - nullable: true - is_free_shipping: - type: boolean - description: | - Flag used to indicate whether the variant has free shipping. If `true`, the shipping cost for the variant will be zero. - fixed_cost_shipping_price: - minimum: 0 - type: number - description: | - A fixed shipping cost for the variant. If defined, this value will be used during checkout instead of normal shipping-cost calculation. - format: double - nullable: true - purchasing_disabled: - type: boolean - description: 'If `true`, this variant will not be purchasable on the storefront.' - purchasing_disabled_message: - maxLength: 255 - minLength: 0 - type: string - description: 'If `purchasing_disabled` is `true`, this message should show on the storefront when the variant is selected.' - upc: - type: string - description: The UPC code used in feeds for shopping comparison sites and external channel integrations. - nullable: true - inventory_level: - type: integer - description: 'Inventory level for the variant, which is used when the product’s inventory_tracking is set to `variant`.' - nullable: true - inventory_warning_level: - type: integer - description: 'When the variant hits this inventory level, it is considered low stock.' - nullable: true - bin_picking_number: - maxLength: 255 - minLength: 0 - type: string - description: Identifies where in a warehouse the variant is located. - nullable: true - description: |- - Variant properties used on: - * `/catalog/products/variants` - * `/catalog/variants` - x-internal: false - product_Base: - title: product_Base - type: object - description: |- - Shared `Product` properties used in: - * `POST` - * `PUT` - * `GET` - x-internal: false - x-examples: - example-1: - id: 0 - name: Smith Journal 13 - type: physical - sku: SM-13 - description: '<p><span>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vel metus ac est egestas porta sed quis erat. Integer id nulla massa. Proin vitae enim nisi. Praesent non dignissim nulla. Nulla mattis id massa ac pharetra. Mauris et nisi in dolor aliquam sodales. Aliquam dui nisl, dictum quis leo sit amet, rutrum volutpat metus. Curabitur libero nunc, interdum ac libero non, tristique porttitor metus. Ut non dignissim lorem, in vestibulum leo. Vivamus sodales quis turpis eget.</span></p>' - weight: 0 - width: 0 - depth: 0 - height: 0 - price: 0 - cost_price: 0 - retail_price: 0 - sale_price: 0 - map_price: 0 - tax_class_id: 0 - product_tax_code: string - categories: - - 0 - brand_id: 0 - inventory_level: 0 - inventory_warning_level: 0 - inventory_tracking: none - fixed_cost_shipping_price: 0 - is_free_shipping: true - is_visible: true - is_featured: true - related_products: - - 0 - warranty: string - bin_picking_number: string - layout_file: string - upc: string - search_keywords: string - availability_description: string - availability: available - gift_wrapping_options_type: any - gift_wrapping_options_list: - - 0 - sort_order: -2147483648 - condition: New - is_condition_shown: true - order_quantity_minimum: 0 - order_quantity_maximum: 0 - page_title: string - meta_keywords: - - string - meta_description: string - view_count: 0 - preorder_release_date: '2019-08-24T14:15:22Z' - preorder_message: string - is_preorder_only: true - is_price_hidden: true - price_hidden_label: string - custom_url: - url: string - is_customized: true - open_graph_type: product - open_graph_title: string - open_graph_description: string - open_graph_use_meta_description: true - open_graph_use_product_name: true - open_graph_use_image: true - brand_name or brand_id: Common Good - gtin: string - mpn: string - reviews_rating_sum: 3.2 - reviews_count: 4 - total_sold: 80 - custom_fields: - - id: 6 - name: ISBN - value: '1234567890123' - bulk_pricing_rules: - - id: 0 - quantity_min: 10 - quantity_max: 50 - type: price - amount: 10 - images: - - image_file: string - is_thumbnail: true - sort_order: -2147483648 - description: string - image_url: string - id: 0 - product_id: 0 - url_zoom: string - url_standard: string - url_thumbnail: string - url_tiny: string - date_modified: '2019-08-24T14:15:22Z' - videos: - - title: Writing Great Documentation - description: A video about documenation - sort_order: 1 - type: youtube - video_id: z3fRu9pkuXE - id: 0 - product_id: 0 - length: string - properties: - name: - maxLength: 250 - minLength: 1 - type: string - description: | - A unique product name. - example: Smith Journal 13 - x-required: - - post - type: - type: string - description: | - The product type. One of: `physical` - a physical stock unit, `digital` - a digital download. - example: physical - enum: - - physical - - digital - x-required: - - post - sku: - maxLength: 255 - minLength: 0 - type: string - description: | - A unique user-defined product code/stock keeping unit (SKU). - example: SM-13 - description: - type: string - description: | - The product description, which can include HTML formatting. - example: '<p><span>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vel metus ac est egestas porta sed quis erat. Integer id nulla massa. Proin vitae enim nisi. Praesent non dignissim nulla. Nulla mattis id massa ac pharetra. Mauris et nisi in dolor aliquam sodales. Aliquam dui nisl, dictum quis leo sit amet, rutrum volutpat metus. Curabitur libero nunc, interdum ac libero non, tristique porttitor metus. Ut non dignissim lorem, in vestibulum leo. Vivamus sodales quis turpis eget.</span></p>' - weight: - maximum: 9999999999 - minimum: 0 - type: number - description: | - Weight of the product, which can be used when calculating shipping costs. This is based on the unit set on the store - format: float - width: - maximum: 9999999999 - minimum: 0 - type: number - description: | - Width of the product, which can be used when calculating shipping costs. - format: float - depth: - maximum: 9999999999 - minimum: 0 - type: number - description: | - Depth of the product, which can be used when calculating shipping costs. - format: float - height: - maximum: 9999999999 - minimum: 0 - type: number - description: | - Height of the product, which can be used when calculating shipping costs. - format: float - price: - minimum: 0 - type: number - description: | - The price of the product. The price should include or exclude tax, based on the store settings. - format: float - cost_price: - minimum: 0 - type: number - description: | - The cost price of the product. Stored for reference only; it is not used or displayed anywhere on the store. - format: float - retail_price: - minimum: 0 - type: number - description: | - The retail cost of the product. If entered, the retail cost price will be shown on the product page. - format: float - sale_price: - minimum: 0 - type: number - description: | - If entered, the sale price will be used instead of value in the price field when calculating the product's cost. - format: float - map_price: - type: number - description: Minimum Advertised Price - tax_class_id: - maximum: 1000000000 - minimum: 0 - type: integer - description: | - The ID of the tax class applied to the product. (NOTE: Value ignored if automatic tax is enabled.) - product_tax_code: - maxLength: 255 - minLength: 0 - type: string - description: | - Accepts AvaTax System Tax Codes, which identify products and services that fall into special sales-tax categories. By using these codes, merchants who subscribe to BigCommerce's Avalara Premium integration can calculate sales taxes more accurately. Stores without Avalara Premium will ignore the code when calculating sales tax. Do not pass more than one code. The codes are case-sensitive. For details, please see Avalara's documentation. - categories: - type: array - description: | - An array of IDs for the categories to which this product belongs. When updating a product, if an array of categories is supplied, all product categories will be overwritten. Does not accept more than 1,000 ID values. - x-required: - - post - items: - type: integer - brand_id: - maximum: 1000000000 - minimum: 0 - type: integer - description: | - A product can be added to an existing brand during a product /PUT or /POST. - inventory_level: - maximum: 2147483647 - minimum: 0 - type: integer - description: | - Current inventory level of the product. Simple inventory tracking must be enabled (See the `inventory_tracking` field) for this to take any effect. - inventory_warning_level: - maximum: 2147483647 - minimum: 0 - type: integer - description: | - Inventory warning level for the product. When the product's inventory level drops below the warning level, the store owner will be informed. Simple inventory tracking must be enabled (see the `inventory_tracking` field) for this to take any effect. - inventory_tracking: - type: string - description: | - The type of inventory tracking for the product. Values are: `none` - inventory levels will not be tracked; `product` - inventory levels will be tracked using the `inventory_level` and `inventory_warning_level` fields; `variant` - inventory levels will be tracked based on variants, which maintain their own warning levels and inventory levels. - enum: - - none - - product - - variant - fixed_cost_shipping_price: - minimum: 0 - type: number - description: | - A fixed shipping cost for the product. If defined, this value will be used during checkout instead of normal shipping-cost calculation. - format: float - is_free_shipping: - type: boolean - description: | - Flag used to indicate whether the product has free shipping. If `true`, the shipping cost for the product will be zero. - is_visible: - type: boolean - description: | - Flag to determine whether the product should be displayed to customers browsing the store. If `true`, the product will be displayed. If `false`, the product will be hidden from view. - is_featured: - type: boolean - description: | - Flag to determine whether the product should be included in the `featured products` panel when viewing the store. - related_products: - type: array - description: | - An array of IDs for the related products. - items: - type: integer - warranty: - maxLength: 65535 - minLength: 0 - type: string - description: | - Warranty information displayed on the product page. Can include HTML formatting. - bin_picking_number: - maxLength: 255 - minLength: 0 - type: string - description: | - The BIN picking number for the product. - layout_file: - maxLength: 500 - minLength: 0 - type: string - description: | - The layout template file used to render this product category. This field is writable only for stores with a Blueprint theme applied. For stores with a Stencil theme applied, see [Custom Template Associations](https://developer.bigcommerce.com/api-reference/store-management/custom-template-associations). - upc: - type: string - maxLength: 32 - minLength: 0 - description: | - The product UPC code, which is used in feeds for shopping comparison sites and external channel integrations. - search_keywords: - maxLength: 65535 - minLength: 0 - type: string - description: | - A comma-separated list of keywords that can be used to locate the product when searching the store. - availability_description: - maxLength: 255 - minLength: 0 - type: string - description: | - Availability text displayed on the checkout page, under the product title. Tells the customer how long it will normally take to ship this product, such as: 'Usually ships in 24 hours.' - availability: - type: string - description: | - Availability of the product. (Corresponds to the product's [Purchasability](https://support.bigcommerce.com/s/article/Adding-Products-v3?language=en_US#sections) section in the control panel.) Supported values: `available` - the product is available for purchase; `disabled` - the product is listed on the storefront, but cannot be purchased; `preorder` - the product is listed for pre-orders. - enum: - - available - - disabled - - preorder - gift_wrapping_options_type: - type: string - description: | - Type of gift-wrapping options. Values: `any` - allow any gift-wrapping options in the store; `none` - disallow gift-wrapping on the product; `list` – provide a list of IDs in the `gift_wrapping_options_list` field. - enum: - - any - - none - - list - gift_wrapping_options_list: - type: array - description: | - A list of gift-wrapping option IDs. - items: - type: integer - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - Priority to give this product when included in product lists on category pages and in search results. Lower integers will place the product closer to the top of the results. - condition: - type: string - description: | - The product condition. Will be shown on the product page if the `is_condition_shown` field's value is `true`. Possible values: `New`, `Used`, `Refurbished`. - enum: - - New - - Used - - Refurbished - is_condition_shown: - type: boolean - description: | - Flag used to determine whether the product condition is shown to the customer on the product page. - order_quantity_minimum: - maximum: 1000000000 - minimum: 0 - type: integer - description: | - The minimum quantity an order must contain, to be eligible to purchase this product. - order_quantity_maximum: - maximum: 1000000000 - minimum: 0 - type: integer - description: | - The maximum quantity an order can contain when purchasing the product. - page_title: - maxLength: 255 - minLength: 0 - type: string - description: | - Custom title for the product page. If not defined, the product name will be used as the meta title. - meta_keywords: - type: array - description: | - Custom meta keywords for the product page. If not defined, the store's default keywords will be used. - items: - type: string - meta_description: - maxLength: 65535 - minLength: 0 - type: string - description: | - Custom meta description for the product page. If not defined, the store's default meta description will be used. - view_count: - maximum: 1000000000 - minimum: 0 - type: integer - description: | - The number of times the product has been viewed. - preorder_release_date: - type: string - description: | - Pre-order release date. See the `availability` field for details on setting a product's availability to accept pre-orders. - format: date-time - nullable: true - preorder_message: - maxLength: 255 - minLength: 0 - type: string - description: | - Custom expected-date message to display on the product page. If undefined, the message defaults to the storewide setting. Can contain the `%%DATE%%` placeholder, which will be substituted for the release date. - is_preorder_only: - type: boolean - description: | - If set to true then on the preorder release date the preorder status will automatically be removed. - If set to false, then on the release date the preorder status **will not** be removed. It will need to be changed manually either in the - control panel or using the API. Using the API set `availability` to `available`. - is_price_hidden: - type: boolean - description: | - False by default, indicating that this product's price should be shown on the product page. If set to `true`, the price is hidden. (NOTE: To successfully set `is_price_hidden` to `true`, the `availability` value must be `disabled`.) - price_hidden_label: - maxLength: 200 - minLength: 0 - type: string - description: | - By default, an empty string. If `is_price_hidden` is `true`, the value of `price_hidden_label` is displayed instead of the price. (NOTE: To successfully set a non-empty string value with `is_price_hidden` set to `true`, the `availability` value must be `disabled`.) - custom_url: - $ref: '#/components/schemas/customUrl_Full' - open_graph_type: - type: string - description: | - Type of product, defaults to `product`. - enum: - - product - - album - - book - - drink - - food - - game - - movie - - song - - tv_show - open_graph_title: - type: string - description: | - Title of the product, if not specified the product name will be used instead. - open_graph_description: - type: string - description: | - Description to use for the product, if not specified then the meta_description will be used instead. - open_graph_use_meta_description: - type: boolean - description: | - Flag to determine if product description or open graph description is used. - open_graph_use_product_name: - type: boolean - description: | - Flag to determine if product name or open graph name is used. - open_graph_use_image: - type: boolean - description: | - Flag to determine if product image or open graph image is used. - brand_name or brand_id: - type: string - description: The brand can be created during a product PUT or POST request. If the brand already exists then the product will be added. If not the brand will be created and the product added. If using `brand_name` it performs a fuzzy match and adds the brand. eg. "Common Good" and "Common good" are the same. Brand name does not return as part of a product response. Only the `brand_id`. - example: Common Good - gtin: - type: string - description: Global Trade Item Number - mpn: - type: string - description: Manufacturer Part Number - reviews_rating_sum: - type: integer - description: | - The total (cumulative) rating for the product. - example: 3 - reviews_count: - type: integer - description: | - The number of times the product has been rated. - example: 4 - total_sold: - type: integer - description: | - The total quantity of this product sold. - example: 80 - custom_fields: - type: array - items: - $ref: '#/components/schemas/productCustomField_Put' - bulk_pricing_rules: - type: array - items: - allOf: - - type: object - properties: - id: - type: integer - description: Unique ID of the *Bulk Pricing Rule*. Read-Only. - readOnly: true - required: - - id - - $ref: '#/components/schemas/bulkPricingRule_Full' - images: - type: array - items: - $ref: '#/components/schemas/productImage_Full' - videos: - type: array - items: - $ref: '#/components/schemas/productVideo_Full' - required: - - name - - type - - weight - - price - metafield_Full: - title: metafield_Full - allOf: - - type: object - properties: - id: - type: integer - description: Unique ID of the *Metafield*. Read-Only. - readOnly: true - example: 6 - - $ref: '#/components/schemas/metafield_Base' - - type: object - properties: - resource_type: - type: string - description: | - The type of resource with which the metafield is associated. - example: product - enum: - - category - - brand - - product - - variant - x-required: - - post - resource_id: - maximum: 10000000000 - minimum: 0 - type: integer - description: | - The ID of the resource with which the metafield is associated. - example: 111 - x-required: - - post - date_created: - type: string - description: | - Date and time of the metafield's creation. Read-Only. - readOnly: true - format: date-time - example: '2018-05-07T20:14:17+00:00' - date_modified: - type: string - description: | - Date and time when the metafield was last updated. Read-Only. - readOnly: true - format: date-time - example: '2018-05-07T20:14:17+00:00' - x-internal: false - productVariant_Put: - title: productVariant_Put - description: The model for a PUT to update variants on a product. - allOf: - - $ref: '#/components/schemas/productVariant_Base' - - type: object - properties: - product_id: - type: integer - x-required: - - post - sku: - maxLength: 255 - minLength: 1 - type: string - x-required: - - post - x-internal: false - errorResponse_409: - title: errorResponse_409 - allOf: - - type: object - properties: - code: - type: integer - status: - type: integer - title: - type: string - description: The error title describing the particular error. - type: - type: string - - type: object - properties: - errors: - $ref: '#/components/schemas/detailedErrors' - x-internal: false - errorResponse_422: - title: errorResponse_422 - allOf: - - type: object - properties: - code: - type: integer - status: - type: integer - title: - type: string - description: The error title describing the particular error. - type: - type: string - - type: object - properties: - errors: - $ref: '#/components/schemas/detailedErrors' - x-internal: false - productSortOrder: - title: productSortOrder - required: - - product_id - - sort_order - type: object - properties: - product_id: - minimum: 1 - type: integer - description: The ID of the associated product. - example: 99 - sort_order: - minimum: 0 - type: integer - example: 4 - description: The relative priority of the product among other products inside the category. - x-internal: false - betacategory_Full: - type: object - description: Common Category object properties. - title: category_Full - properties: - id: - type: integer - description: |- - Unique ID of the *Category*. Increments sequentially. - Read-Only. - readOnly: true - parent_id: - type: integer - description: |- - The unique numeric ID of the category's parent. This field controls where the category sits in the tree of categories that organize the catalog. - Required in a POST if creating a child category. - example: 2 - required: - - post - name: - type: string - description: |- - The name displayed for the category. Name is unique with respect to the category's siblings. - Required in a POST. - minLength: 1 - maxLength: 50 - example: Bath - required: - - post - description: - type: string - description: | - The product description, which can include HTML formatting. - example: We offer a wide variety of products perfect for relaxing - views: - type: integer - description: | - Number of views the category has on the storefront. - example: 1050 - sort_order: - type: integer - description: | - Priority this category will be given when included in the menu and category pages. The lower the number, the closer to the top of the results the category will be. - minimum: -2147483648 - maximum: 2147483647 - example: 3 - page_title: - type: string - description: | - Custom title for the category page. If not defined, the category name will be used as the meta title. - minLength: 0 - maxLength: 255 - example: Bath - search_keywords: - type: string - description: | - A comma-separated list of keywords that can be used to locate the category when searching the store. - minLength: 0 - maxLength: 255 - meta_keywords: - type: array - description: | - Custom meta keywords for the category page. If not defined, the store's default keywords will be used. Must post as an array like: ["awesome","sauce"]. - items: - type: string - meta_description: - type: string - description: | - Custom meta description for the category page. If not defined, the store's default meta description will be used. - minLength: 0 - maxLength: 65535 - layout_file: - type: string - description: | - A valid layout file. (Please refer to [this article](https://support.bigcommerce.com/articles/Public/Creating-Custom-Template-Files/) on creating category files.) This field is writable only for stores with a Blueprint theme applied. - minLength: 0 - maxLength: 500 - example: category.html - is_visible: - type: boolean - description: | - Flag to determine whether the product should be displayed to customers browsing the store. If `true`, the category will be displayed. If `false`, the category will be hidden from view. - default_product_sort: - type: string - description: | - Determines how the products are sorted on category page load. - enum: - - use_store_settings - - featured - - newest - - best_selling - - alpha_asc - - alpha_desc - - avg_customer_review - - price_asc - - price_desc - image_url: - type: string - description: | - Image URL used for this category on the storefront. Images can be uploaded via form file post to `/categories/{categoryId}/image`, or by providing a publicly accessible URL in this field. - x-url: true - example: 'https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png' - custom_url: - $ref: '#/components/schemas/betacustomUrl_Full' - required: - - parent_id - - name - x-tags: - - Models - betametaCollection_Full: - type: object - description: 'Data about the response, including pagination and collection totals.' - title: metaCollection_Full - properties: - pagination: - $ref: '#/components/schemas/betapagination_Full' - x-tags: - - Models - betapagination_Full: - type: object - description: 'Data about the response, including pagination and collection totals.' - title: pagination_Full - properties: - total: - type: integer - description: | - Total number of items in the result set. - example: 36 - count: - type: integer - description: | - Total number of items in the collection response. - example: 36 - per_page: - type: integer - description: | - The amount of items returned in the collection per page, controlled by the limit parameter. - example: 50 - current_page: - type: integer - description: | - The page you are currently on within the collection. - example: 1 - total_pages: - type: integer - description: | - The total number of pages in the collection. - example: 1 - links: - type: object - description: | - Pagination links for the previous and next parts of the whole collection. - properties: - previous: - type: string - description: | - Link to the previous page returned in the response. - current: - type: string - description: | - Link to the current page returned in the response. - example: '?page=1&limit=50' - next: - type: string - description: | - Link to the next page returned in the response. - x-tags: - - Models - betametaEmpty_Full: - type: object - title: Response meta - properties: {} - additionalProperties: true - description: Response metadata. - x-tags: - - Models - betaerrorResponse_Full: - allOf: - - $ref: '#/components/schemas/betaerror_Base' - - type: object - properties: - errors: - $ref: '#/components/schemas/betadetailedErrors' - title: errorResponse_Full - x-tags: - - Models - betaerror_Base: - type: object - description: | - Error payload for the BigCommerce API. - properties: - status: - description: | - The HTTP status code. - type: integer - title: - description: | - The error title describing the particular error. - type: string - type: - type: string - instance: - type: string - title: error_Base - x-tags: - - Models - betaerrorNotFound: - description: Error payload for the BigCommerce API. - type: object - properties: - status: - description: | - 404 HTTP status code. - type: integer - title: - description: The error title describing the particular error. - type: string - type: - type: string - instance: - type: string - title: errorNotFound - x-tags: - - Models - betaerrorNoContent: - description: No-content response for the BigCommerce API. - type: object - properties: - status: - description: | - 204 HTTP status code. - type: integer - title: - description: The error title describing the situation. - type: string - type: - type: string - instance: - type: string - title: errorNoContent - x-tags: - - Models - betadetailedErrors: - type: object - title: detailedErrors - properties: {} - additionalProperties: true - x-tags: - - Models - betaerrorResponse_409: - title: errorResponse_409 - allOf: - - properties: - code: - type: integer - status: - type: integer - title: - type: string - description: The error title describing the particular error. - type: - type: string - - properties: - errors: - $ref: '#/components/schemas/betadetailedErrors' - type: object - x-tags: - - Models - betaerrorResponse_422: - title: errorResponse_422 - allOf: - - properties: - code: - type: integer - status: - type: integer - title: - type: string - description: The error title describing the particular error. - type: - type: string - - properties: - errors: - $ref: '#/components/schemas/betadetailedErrors' - type: object - x-tags: - - Models - custom_url: - type: object - description: The custom URL for the category on the storefront. - title: Custom Url Category - properties: - url: - type: string - description: | - Category URL on the storefront. - x-url: true - minLength: 0 - maxLength: 255 - example: /shoes - required: - - post - - put - is_customized: - type: boolean - description: | - Returns `true` if the URL has been changed from its default state (the auto-assigned URL that BigCommerce provides). - required: - - post - - put - x-tags: - - Models - betacustomUrl_Full: - type: object - description: The custom URL for the product on the storefront. - title: customUrl_Full - properties: - url: - type: string - description: | - Product URL on the storefront. - x-url: true - minLength: 0 - maxLength: 255 - example: /shoes - required: - - post - - put - is_customized: - type: boolean - description: | - Returns `true` if the URL has been changed from its default state (the auto-assigned URL that BigCommerce provides). - required: - - post - - put - x-tags: - - Models - CreateCategories: - type: array - items: - allOf: - - $ref: '#/components/schemas/TreeIdCreateData' - - $ref: '#/components/schemas/ParentIdCreateData' - - $ref: '#/components/schemas/CategoryDataPOST' - x-tags: - - Models - title: Create Categories - UpdateCategories: - x-tags: - - Models - type: array - items: - allOf: - - $ref: '#/components/schemas/TreeIdUpdateData' - - $ref: '#/components/schemas/CategoryIdUpdateData' - - $ref: '#/components/schemas/CategoryUuidData' - - $ref: '#/components/schemas/ParentIdUpdateData' - - $ref: '#/components/schemas/CategoryDataPUT' - Category: - x-tags: - - Models - title: Category - allOf: - - $ref: '#/components/schemas/id' - - $ref: '#/components/schemas/parent_id' - - $ref: '#/components/schemas/name' - - $ref: '#/components/schemas/description' - - $ref: '#/components/schemas/views' - - $ref: '#/components/schemas/sort_order' - - $ref: '#/components/schemas/page_title' - - $ref: '#/components/schemas/meta_keywords' - - $ref: '#/components/schemas/meta_description' - - $ref: '#/components/schemas/layout_file' - - $ref: '#/components/schemas/image_url' - - $ref: '#/components/schemas/is_visible' - - $ref: '#/components/schemas/search_keywords' - - $ref: '#/components/schemas/default_product_sort' - - type: object - properties: - url: - $ref: '#/components/schemas/Url' - x-examples: {} - CategoryUuidData: - type: object - x-tags: - - Models - properties: - category_uuid: - type: string - format: uuid - title: category_uuid - CategoryIdUpdateData: - type: object - properties: - category_id: - type: integer - required: - - category_id - x-tags: - - Models - ParentIdCreateData: - type: object - properties: - parent_id: - type: integer - required: - - parent_id - x-tags: - - Models - TreeIdCreateData: - type: object - properties: - tree_id: - type: integer - required: - - tree_id - x-tags: - - Models - ParentIdUpdateData: - type: object - properties: - parent_id: - type: integer - x-tags: - - Models - TreeIdUpdateData: - type: object - x-tags: - - Models - properties: - tree_id: - type: integer - required: - - tree_id - CategoryData: - allOf: - - type: object - properties: - name: - type: string - description: - type: string - views: - type: integer - sort_order: - type: integer - page_title: - type: string - search_keywords: - type: string - meta_keywords: - type: array - items: - type: string - meta_description: - type: string - layout_file: - type: string - is_visible: - type: boolean - image_url: - type: string - url: - $ref: '#/components/schemas/Url' - CategoryDataPUT: - allOf: - - $ref: '#/components/schemas/CategoryData' - - $ref: '#/components/schemas/default_product_sort' - CategoryDataPOST: - allOf: - - $ref: '#/components/schemas/CategoryData' - - $ref: '#/components/schemas/default_product_sort' - required: - - name - - url - Urls: - type: array - items: - $ref: '#/components/schemas/Url' - x-tags: - - Models - Url: - type: object - properties: - path: - type: string - is_customized: - type: boolean - x-tags: - - Models - MetaPagination: - type: object - properties: - pagination: - type: object - properties: - total: - type: integer - example: 246 - minimum: 0 - count: - type: integer - example: 5 - minimum: 0 - per_page: - type: integer - example: 5 - minimum: 0 - current_page: - type: integer - example: 1 - minimum: 1 - total_pages: - type: integer - example: 50 - minimum: 0 - links: - type: object - properties: - previous: - type: string - example: '?limit=5&page=1' - current: - type: string - example: '?limit=5&page=2' - next: - type: string - example: '?limit=5&page=3' - x-tags: - - Models - DetailedErrors: - description: | - Details of errors. - type: object - properties: {} - additionalProperties: true - x-tags: - - Models - ErrorRequest: - type: object - properties: - errors: - type: array - items: - $ref: '#/components/schemas/ErrorBasic' - x-tags: - - Models - ErrorBasic: - type: object - properties: - status: - description: | - The HTTP status code. - type: integer - title: - description: | - The error title describing the particular error. - type: string - type: - type: string - x-tags: - - Models - ErrorAdditional: - type: object - properties: - errors: - $ref: '#/components/schemas/DetailedErrors' - x-tags: - - Models - MetaError: - allOf: - - $ref: '#/components/schemas/ErrorBasic' - - $ref: '#/components/schemas/ErrorAdditional' - x-tags: - - Models - MetaData: - type: object - properties: - total: - type: integer - success: - type: integer - failed: - type: integer - x-tags: - - Models - SuccessNoContentResponse: - type: object - properties: - meta: - $ref: '#/components/schemas/MetaData' - x-tags: - - Models - PartialSuccessNoContentResponse: - type: object - properties: - errors: - $ref: '#/components/schemas/MetaError' - meta: - $ref: '#/components/schemas/MetaData' - x-tags: - - Models - PartialSuccessResponse: - type: object - properties: - data: - type: array - items: - $ref: '#/components/schemas/Category' - meta: - $ref: '#/components/schemas/MetaData' - x-tags: - - Models - SuccessResponse: - type: object - properties: - data: - type: array - items: - $ref: '#/components/schemas/Category' - errors: - $ref: '#/components/schemas/MetaError' - meta: - $ref: '#/components/schemas/MetaData' - x-tags: - - Models - ErrorResponse: - type: object - properties: - errors: - $ref: '#/components/schemas/MetaError' - meta: - $ref: '#/components/schemas/MetaData' - x-tags: - - Models - Tree: - type: object - properties: - id: - type: integer - name: - type: string - minLength: 1 - maxLength: 255 - channels: - type: array - items: - type: integer - x-tags: - - Models - CategoryNode: - type: object - properties: - id: - type: integer - parent_id: - type: integer - depth: - type: integer - path: - type: array - items: - type: integer - name: - type: string - is_visible: - type: boolean - children: - type: array - items: - $ref: '#/components/schemas/CategoryNode' - x-tags: - - Models - beta4Category: - type: object - properties: - id: - type: integer - parent_id: - type: integer - tree_id: - type: integer - name: - type: string - description: - type: string - views: - type: integer - sort_order: - type: integer - page_title: - type: string - search_keywords: - type: string - meta_keywords: - type: array - items: - type: string - meta_description: - type: string - layout_file: - type: string - is_visible: - type: boolean - default_product_sort: - type: string - image_url: - type: string - custom_url: - $ref: '#/components/schemas/CustomUrl' - x-tags: - - Models - beta4CategoryData: - type: object - properties: - tree_id: - type: integer - parent_id: - type: integer - name: - type: string - description: - type: string - views: - type: integer - sort_order: - type: integer - page_title: - type: string - search_keywords: - type: string - meta_keywords: - type: array - items: - type: string - meta_description: - type: string - layout_file: - type: string - is_visible: - type: boolean - default_product_sort: - type: string - image_url: - type: string - custom_url: - $ref: '#/components/schemas/CustomUrl' - x-tags: - - Models - CustomUrl: - type: object - properties: - url: - type: string - is_customized: - type: boolean - x-tags: - - Models - MetaPaginationObject: - type: object - properties: - pagination: - type: object - properties: - total: - type: integer - example: 246 - minimum: 0 - count: - type: integer - example: 5 - minimum: 0 - per_page: - type: integer - example: 5 - minimum: 0 - current_page: - type: integer - example: 1 - minimum: 1 - total_pages: - type: integer - example: 50 - minimum: 0 - links: - type: object - properties: - next: - type: string - example: '?limit=5&page=2' - current: - type: string - example: '?limit=5&page=1' - x-tags: - - Models - beta4DetailedErrors: - type: object - properties: {} - additionalProperties: true - x-tags: - - Models - BaseError: - type: object - description: | - Error payload for the BigCommerce API. - properties: - status: - description: | - The HTTP status code. - type: integer - title: - description: | - The error title describing the particular error. - type: string - type: - type: string - instance: - type: string - x-tags: - - Models - beta4ErrorResponse: - allOf: - - $ref: '#/components/schemas/BaseError' - - type: object - properties: - errors: - $ref: '#/components/schemas/beta4DetailedErrors' - x-tags: - - Models - ProductsChannelCount: - type: object - description: The count of product in the channels. - properties: - channel_id: - description: Channel ID. - type: integer - minimum: 1 - product_count: - type: integer - minimum: 0 - x-tags: - - Models - ProductsCategoriesCount: - properties: - product_id: - type: integer - minimum: 1 - channels: - type: array - items: - $ref: '#/components/schemas/CategoriesCount' - x-tags: - - Models - CategoriesCount: - properties: - channel_id: - type: integer - minimum: 1 - category_count: - type: integer - minimum: 0 - x-tags: - - Models - ProductChannelAssignment: - properties: - product_id: - type: integer - channel_id: - type: integer - x-tags: - - Models - ProductCategoryAssignment: - properties: - product_id: - type: integer - category_id: - type: integer - x-tags: - - Models - beta5DetailedErrors: - type: object - properties: {} - additionalProperties: true - x-tags: - - Models - beta5ErrorResponse: - allOf: - - $ref: '#/components/schemas/BaseError' - - type: object - properties: - errors: - $ref: '#/components/schemas/beta5DetailedErrors' - x-tags: - - Models - default_product_sort: - title: default_product_sort - type: object - properties: - default_product_sort: - type: string - description: | - Determines how the products are sorted on category page load. - enum: - - use_store_settings - - featured - - newest - - best_selling - - alpha_asc - - alpha_desc - - avg_customer_review - - price_asc - - price_desc - name: - title: name - type: object - properties: - name: - maxLength: 50 - minLength: 1 - type: string - description: |- - The name displayed for the category. Name is unique with respect to the category's siblings. - Required in a POST. - example: Bath - description: - title: description - type: object - properties: - description: - type: string - description: | - The product description, which can include HTML formatting. - example: <p>We offer a wide variety of products perfect for relaxing</p> - views: - title: views - type: object - properties: - views: - type: integer - description: | - Number of views the category has on the storefront. - example: 1050 - sort_order: - title: sort_order - type: object - properties: - sort_order: - type: integer - description: | - Priority this category will be given when included in the menu and category pages. The lower the number, the closer to the top of the results the category will be. - example: 3 - page_title: - title: page_title - type: object - properties: - page_title: - type: string - description: | - Custom title for the category page. If not defined, the category name will be used as the meta title. - example: Bath - search_keywords: - title: search_keywords - type: object - properties: - search_keywords: - type: string - description: | - A comma-separated list of keywords that can be used to locate the category when searching the store. - meta_keywords: - title: meta_keywords - type: object - properties: - meta_keywords: - type: array - description: | - Custom meta keywords for the category page. If not defined, the store's default keywords will be used. Must post as an array like: ["awesome","sauce"]. - items: - type: string - layout_file: - title: layout_file - type: object - properties: - layout_file: - maxLength: 500 - minLength: 0 - type: string - description: | - A valid layout file. (Please refer to [this article](https://support.bigcommerce.com/articles/Public/Creating-Custom-Template-Files/) on creating category files.) This field is writable only for stores with a Blueprint theme applied. - example: category.html - is_visible: - title: is_visible - type: object - properties: - is_visible: - type: boolean - description: | - Flag to determine whether the product should be displayed to customers browsing the store. If `true`, the category will be displayed. If `false`, the category will be hidden from view. - image_url: - title: image_url - type: object - properties: - image_url: - type: string - description: | - Image URL used for this category on the storefront. Images can be uploaded via form file post to `/categories/{categoryId}/image`, or by providing a publicly accessible URL in this field. - example: 'https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png' - x-url: true - meta_description: - title: meta_description - type: object - properties: - meta_description: - maxLength: 65535 - minLength: 0 - type: string - description: | - Custom meta description for the category page. If not defined, the store's default meta description will be used. - id: - title: id - type: object - properties: - id: - type: integer - description: |- - Unique ID of the *Category*. Increments sequentially. - Read-Only. - readOnly: true - parent_id: - title: parent_id - type: object - properties: - parent_id: - type: integer - description: |- - The unique numeric ID of the category's parent. This field controls where the category sits in the tree of categories that organize the catalog. - Required in a POST if creating a child category. - example: 2 - responses: - BrandCollectionResponse: - description: '' - content: - application/json: - schema: - title: Brand Collection Response - type: object - properties: - data: - type: array - items: - title: Brand - required: - - name - type: object - properties: - id: - type: integer - description: Unique ID of the *Brand*. Read-Only. - readOnly: true - name: - maxLength: 255 - minLength: 1 - type: string - description: |- - The name of the brand. Must be unique. - Required in POST. - example: Common Good - x-required: - - post - - put - page_title: - maxLength: 255 - minLength: 0 - type: string - description: | - The title shown in the browser while viewing the brand. - example: Common Good - meta_keywords: - type: array - description: | - Comma-separated list of meta keywords to include in the HTML. - items: - type: string - example: 'modern, clean, contemporary' - meta_description: - maxLength: 65535 - minLength: 0 - type: string - description: | - A meta description to include. - example: Common Good is a modern brand. - search_keywords: - maxLength: 65535 - minLength: 0 - type: string - description: | - A comma-separated list of keywords that can be used to locate this brand. - example: 'kitchen, laundry, cart, storage' - image_url: - type: string - description: | - Image URL used for this category on the storefront. Images can be uploaded via form file post to `/brands/{brandId}/image`, or by providing a publicly accessible URL in this field. - example: 'https://cdn8.bigcommerce.com/s-12345/product_images/k/your-image-name.png' - x-url: true - custom_url: - title: Custom Url Brand - type: object - properties: - url: - type: string - description: | - Brand URL on the storefront. - example: /shoes - x-url: true - is_customized: - type: boolean - description: | - Returns `true` if the URL has been changed from its default state (the auto-assigned URL that BigCommerce provides). - example: true - description: The custom URL for the brand on the storefront. - description: Common Brand properties. - meta: - $ref: '#/components/schemas/metaCollection_Full' - BrandImageUpload: - description: '' - content: - application/json: - schema: - type: object - properties: - data: - type: object - properties: - image_url: - type: string - meta: - $ref: '#/components/schemas/metaEmpty_Full' - example: - data: - image_url: 'https://cdn11.bigcommerce.com/s-{store_hash}/product_images/k/group_1545334669__76009.png' - meta: {} - BrandResponse: - description: '' - content: - application/json: - schema: - title: Brand Response - type: object - properties: - data: - title: Brand - required: - - name - type: object - properties: - id: - type: integer - description: Unique ID of the *Brand*. Read-Only. - readOnly: true - name: - maxLength: 255 - minLength: 1 - type: string - description: |- - The name of the brand. Must be unique. - Required in POST. - example: Common Good - x-required: - - post - - put - page_title: - maxLength: 255 - minLength: 0 - type: string - description: | - The title shown in the browser while viewing the brand. - example: Common Good - meta_keywords: - type: array - description: | - Comma-separated list of meta keywords to include in the HTML. - items: - type: string - example: 'modern, clean, contemporary' - meta_description: - maxLength: 65535 - minLength: 0 - type: string - description: | - A meta description to include. - example: Common Good is a modern brand. - search_keywords: - maxLength: 65535 - minLength: 0 - type: string - description: | - A comma-separated list of keywords that can be used to locate this brand. - example: 'kitchen, laundry, cart, storage' - image_url: - type: string - description: | - Image URL used for this category on the storefront. Images can be uploaded via form file post to `/brands/{brandId}/image`, or by providing a publicly accessible URL in this field. - example: 'https://cdn8.bigcommerce.com/s-12345/product_images/k/your-image-name.png' - x-url: true - custom_url: - title: Custom Url Brand - type: object - properties: - url: - type: string - description: | - Brand URL on the storefront. - example: /shoes - x-url: true - is_customized: - type: boolean - description: | - Returns `true` if the URL has been changed from its default state (the auto-assigned URL that BigCommerce provides). - example: true - description: The custom URL for the brand on the storefront. - description: Common Brand properties. - meta: - $ref: '#/components/schemas/metaEmpty_Full' - description: |- - Brand Response returns for: - * Create Brand - * Get Brand by Id - * Update Brand by Id - example: - data: - id: 50 - name: Common Good - meta_keywords: - - 'modern, clean, contemporary' - meta_description: Common Good is a modern brand - image_url: '' - search_keywords: 'kitchen, laundry, cart, storage' - custom_url: - url: /brands/Common-Good.html - is_customized: false - meta: {} - BulkPricingRuleCollectionResponse: - description: '' - content: - application/json: - schema: - type: object - properties: - data: - type: array - items: - $ref: '#/components/schemas/bulkPricingRule_Full' - meta: - $ref: '#/components/schemas/metaCollection_Full' - BulkPricingRuleResponse: - description: '' - content: - application/json: - schema: - type: object - properties: - data: - $ref: '#/components/schemas/bulkPricingRule_Full' - meta: - $ref: '#/components/schemas/metaEmpty_Full' - example: - data: - id: 83 - quantity_min: 1 - quantity_max: 3 - type: price - amount: 1 - meta: {} - CatalogSummaryResponse: - description: '' - content: - application/json: - schema: - title: Catalog Summary Response - type: object - properties: - data: - title: Catalog Summary - type: object - properties: - inventory_count: - type: integer - description: | - A count of all inventory items in the catalog. - example: 2000 - inventory_value: - type: number - description: | - Total value of store's inventory. - format: double - example: 267000 - primary_category_id: - type: integer - description: | - ID of the category containing the most products. - example: 23 - primary_category_name: - type: string - description: | - Name of the category containing the most products. - example: Shop All - variant_count: - type: integer - description: Total number of variants - example: 46 - highest_variant_price: - type: number - description: Highest priced variant - format: double - example: 249 - average_variant_price: - type: number - description: Average price of all variants - format: double - example: 83.07978261 - lowest_variant_price: - type: string - description: Lowest priced variant in the store - example: '7' - oldest_variant_date: - type: string - example: '2018-08-15T00:00:00+00:00' - newest_variant_date: - type: string - example: '2018-08-16T00:00:00+00:00' - description: Catalog Summary object describes a lightweight summary of the catalog. - meta: - title: Meta - type: object - properties: {} - description: Empty meta object; may be used later. - CatalogVariantCollectionResponse: - description: '' - content: - application/json: - schema: - title: Variant Collection Response - type: object - properties: - data: - type: array - items: - type: object - allOf: - - title: Variant Base - type: object - properties: - cost_price: - minimum: 0 - type: number - description: The cost price of the variant. Not affected by Price List prices. - format: double - x-nullable: true - price: - minimum: 0 - type: number - description: 'This variant’s base price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is `null`, the product’s default price (set in the Product resource’s `price` field) will be used as the base price.' - format: double - x-nullable: true - sale_price: - minimum: 0 - type: number - description: 'This variant’s sale price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s sale price (set in the Product resource’s `price` field) will be used as the sale price.' - format: double - x-nullable: true - retail_price: - minimum: 0 - type: number - description: 'This variant’s retail price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s retail price (set in the Product resource’s `price` field) will be used as the retail price.' - format: double - x-nullable: true - weight: - minimum: 0 - type: number - description: 'This variant’s base weight on the storefront. If this value is null, the product’s default weight (set in the Product resource’s weight field) will be used as the base weight.' - format: double - x-nullable: true - width: - minimum: 0 - type: number - description: | - Width of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default width (set in the Product resource's `width` field) will be used as the base width. - format: double - x-nullable: true - height: - minimum: 0 - type: number - description: | - Height of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default height (set in the Product resource's `height` field) will be used as the base height. - format: double - x-nullable: true - depth: - minimum: 0 - type: number - description: | - Depth of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default depth (set in the Product resource's `depth` field) will be used as the base depth. - format: double - x-nullable: true - is_free_shipping: - type: boolean - description: | - Flag used to indicate whether the variant has free shipping. If `true`, the shipping cost for the variant will be zero. - fixed_cost_shipping_price: - minimum: 0 - type: number - description: | - A fixed shipping cost for the variant. If defined, this value will be used during checkout instead of normal shipping-cost calculation. - format: double - x-nullable: true - purchasing_disabled: - type: boolean - description: 'If `true`, this variant will not be purchasable on the storefront.' - purchasing_disabled_message: - maxLength: 255 - minLength: 0 - type: string - description: 'If `purchasing_disabled` is `true`, this message should show on the storefront when the variant is selected.' - upc: - type: string - description: The UPC code used in feeds for shopping comparison sites and external channel integrations. - x-nullable: true - inventory_level: - type: integer - description: 'Inventory level for the variant, which is used when the product’s inventory_tracking is set to `variant`.' - x-nullable: true - inventory_warning_level: - type: integer - description: 'When the variant hits this inventory level, it is considered low stock.' - x-nullable: true - bin_picking_number: - maxLength: 255 - minLength: 0 - type: string - description: Identifies where in a warehouse the variant is located. - x-nullable: true - description: Common Variant properties. - - type: object - properties: - id: - type: integer - product_id: - type: integer - sku: - type: string - sku_id: - type: integer - description: Read-only reference to v2 API's SKU ID. Null if it is a base variant. - x-nullable: true - option_values: - type: array - description: Array of option and option values IDs that make up this variant. Will be empty if the variant is the product's base variant. - items: - title: Option Value Variant - type: object - allOf: - - title: Option Value Product Base - type: object - properties: - option_display_name: - maxLength: 255 - minLength: 1 - type: string - description: | - The name of the option. - example: Color - x-required: - - post - label: - maxLength: 255 - minLength: 1 - type: string - description: | - The label of the option value. - example: Beige - x-required: - - post - description: Common Option Value Product properties. - - type: object - properties: - id: - type: integer - option_id: - type: integer - calculated_price: - type: number - description: | - The price of the variant as seen on the storefront. This price takes into account `sale_price` and any price adjustment rules that are applicable to this variant. - format: double - meta: - $ref: '#/components/schemas/metaCollection_Full' - CategoryCollectionResponse: - description: '' - content: - application/json: - schema: - title: Category Base - type: object - properties: - data: - type: array - items: - type: object - meta: - $ref: '#/components/schemas/metaCollection_Full' - example: - data: - - id: 19 - parent_id: 0 - name: Garden - description: <p>This is the garden description</p> - views: 0 - sort_order: 2 - page_title: page title - meta_keywords: - - meta keyword - meta_description: meta description - layout_file: category.html - image_url: '' - is_visible: true - search_keywords: search keywords - default_product_sort: use_store_settings - custom_url: - url: /garden/ - is_customized: false - - id: 20 - parent_id: 0 - name: Publications - description: '' - views: 0 - sort_order: 4 - page_title: '' - meta_keywords: - - '' - meta_description: '' - layout_file: category_with_facets.html - image_url: '' - is_visible: true - search_keywords: '' - default_product_sort: use_store_settings - custom_url: - url: /publications/ - is_customized: false - - id: 21 - parent_id: 0 - name: Kitchen - description: '' - views: 0 - sort_order: 3 - page_title: '' - meta_keywords: - - '' - meta_description: '' - layout_file: category_with_facets.html - image_url: '' - is_visible: true - search_keywords: '' - default_product_sort: use_store_settings - custom_url: - url: /kitchen/ - is_customized: false - - id: 22 - parent_id: 0 - name: Utility - description: '' - views: 0 - sort_order: 5 - page_title: '' - meta_keywords: - - '' - meta_description: '' - layout_file: category_with_facets.html - image_url: '' - is_visible: true - search_keywords: '' - default_product_sort: use_store_settings - custom_url: - url: /utility/ - is_customized: false - - id: 23 - parent_id: 0 - name: Shop All - description: '' - views: 0 - sort_order: 0 - page_title: '' - meta_keywords: - - '' - meta_description: '' - layout_file: category_with_facets.html - image_url: '' - is_visible: true - search_keywords: '' - default_product_sort: use_store_settings - custom_url: - url: /shop-all/ - is_customized: false - - id: 39 - parent_id: 19 - name: Bath - description: '' - views: 0 - sort_order: 0 - page_title: '' - meta_keywords: - - '' - meta_description: '' - layout_file: category.html - image_url: '' - is_visible: true - search_keywords: '' - default_product_sort: use_store_settings - custom_url: - url: /garden/bath/ - is_customized: false - meta: - pagination: - total: 6 - count: 6 - per_page: 50 - current_page: 1 - total_pages: 1 - links: - current: '?page=1&limit=50' - CategoryResponse: - description: '' - content: - application/json: - schema: - title: Category Response - type: object - properties: - data: - $ref: '#/components/schemas/category_Full' - meta: - title: Meta - type: object - properties: {} - description: Empty meta object; may be used later. - ComplexRuleCollectionResponse: - description: '' - content: - application/json: - schema: - title: Complex Rule Collection Response - type: object - properties: - data: - type: array - items: - title: Complex Rule - type: object - properties: - id: - type: integer - description: |- - The unique numeric ID of the rule; increments sequentially. - Read-Only - example: 5 - product_id: - type: integer - description: | - The unique numeric ID of the product with which the rule is associated; increments sequentially. - nullable: true - example: 67 - x-required: - - post - - put - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The priority to give this rule when making adjustments to the product properties. - example: 0 - enabled: - type: boolean - description: | - Flag for determining whether the rule is to be used when adjusting a product's price, weight, image, or availabilty. - example: true - stop: - type: boolean - description: | - Flag for determining whether other rules should not be applied after this rule has been applied. - purchasing_disabled: - type: boolean - description: | - Flag for determining whether the rule should disable purchasing of a product when the conditions are applied. - purchasing_disabled_message: - maxLength: 255 - minLength: 0 - type: string - description: | - Message displayed on the storefront when a rule disables the purchasing of a product. - example: This product is not available at this time. - purchasing_hidden: - type: boolean - description: | - Flag for determining whether the rule should hide purchasing of a product when the conditions are applied. - image_url: - type: string - description: | - The URL for an image displayed on the storefront when the conditions are applied. Limit of 8MB per file. - example: 'https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png' - price_adjuster: - title: Adjuster - type: object - properties: - adjuster: - type: string - description: | - The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - nullable: true - enum: - - relative - - percentage - adjuster_value: - type: number - description: | - The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. - example: 5 - description: Adjuster for Complex Rules. - weight_adjuster: - title: Adjuster - type: object - properties: - adjuster: - type: string - description: | - The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - nullable: true - enum: - - relative - - percentage - adjuster_value: - type: number - description: | - The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. - example: 5 - description: Adjuster for Complex Rules. - conditions: - type: array - items: - title: Complex Rule Condition - required: - - modifier_id - - modifier_value_id - - variant_id - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the rule condition; increments sequentially. Read-Only - nullable: true - example: 3 - rule_id: - type: integer - description: |- - The unique numeric ID of the rule with which the condition is associated. - Read-Only - nullable: true - example: 4 - modifier_id: - type: integer - description: |- - The unique numeric ID of the modifier with which the rule condition is associated. - Required in /POST. - nullable: true - example: 55 - modifier_value_id: - type: integer - description: |- - The unique numeric ID of the modifier value with which the rule condition is associated. - Required in /POST. - nullable: true - example: 256 - variant_id: - type: integer - description: |- - The unique numeric ID of the variant with which the rule condition is associated. - Required in /POST. - nullable: true - example: 1 - combination_id: - type: integer - description: | - (READ-ONLY:) The unique numeric ID of the SKU (v2 API), or Combination, with which the rule condition is associated. This is to maintain cross-compatibility between v2 and v3. - description: 'Complex rules may return with conditions that apply to one or more variants, or with a single modifier value (if the rules were created using the v2 API or the control panel). Complex rules created or updated in the v3 API must have conditions that either reference multiple `modifier_value_id`’s, or else reference a `modifier_value_id` and a `variant_id`.' - description: Common ComplexRule properties. - meta: - $ref: '#/components/schemas/metaCollection_Full' - description: Complex Rule Response - ComplexRuleResponse: - description: '' - content: - application/json: - schema: - type: object - properties: - data: - title: Complex Rule - type: object - properties: - id: - type: integer - description: |- - The unique numeric ID of the rule; increments sequentially. - Read-Only - example: 5 - product_id: - type: integer - description: | - The unique numeric ID of the product with which the rule is associated; increments sequentially. - example: 67 - x-required: - - post - - put - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The priority to give this rule when making adjustments to the product properties. - example: 0 - enabled: - type: boolean - description: | - Flag for determining whether the rule is to be used when adjusting a product's price, weight, image, or availabilty. - example: true - stop: - type: boolean - description: | - Flag for determining whether other rules should not be applied after this rule has been applied. - purchasing_disabled: - type: boolean - description: | - Flag for determining whether the rule should disable purchasing of a product when the conditions are applied. - purchasing_disabled_message: - maxLength: 255 - minLength: 0 - type: string - description: | - Message displayed on the storefront when a rule disables the purchasing of a product. - example: This product is not available at this time. - purchasing_hidden: - type: boolean - description: | - Flag for determining whether the rule should hide purchasing of a product when the conditions are applied. - image_url: - type: string - description: | - The URL for an image displayed on the storefront when the conditions are applied. Limit of 8MB per file. - example: 'https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png' - price_adjuster: - title: Adjuster - type: object - properties: - adjuster: - type: string - description: | - The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - enum: - - relative - - percentage - adjuster_value: - type: number - description: | - The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. - example: 5 - description: Adjuster for Complex Rules. - weight_adjuster: - title: Adjuster - type: object - properties: - adjuster: - type: string - description: | - The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - enum: - - relative - - percentage - adjuster_value: - type: number - description: | - The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. - example: 5 - description: Adjuster for Complex Rules. - conditions: - type: array - items: - title: Complex Rule Condition - required: - - modifier_id - - modifier_value_id - - variant_id - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the rule condition; increments sequentially. Read-Only - example: 3 - rule_id: - type: integer - description: |- - The unique numeric ID of the rule with which the condition is associated. - Read-Only - example: 4 - modifier_id: - type: integer - description: |- - The unique numeric ID of the modifier with which the rule condition is associated. - Required in /POST. - example: 55 - modifier_value_id: - type: integer - description: |- - The unique numeric ID of the modifier value with which the rule condition is associated. - Required in /POST. - example: 256 - variant_id: - type: integer - description: |- - The unique numeric ID of the variant with which the rule condition is associated. - Required in /POST. - example: 1 - combination_id: - type: integer - description: | - (READ-ONLY:) The unique numeric ID of the SKU (v2 API), or Combination, with which the rule condition is associated. This is to maintain cross-compatibility between v2 and v3. - description: 'Complex rules may return with conditions that apply to one or more variants, or with a single modifier value (if the rules were created using the v2 API or the control panel). Complex rules created or updated in the v3 API must have conditions that either reference multiple `modifier_value_id`’s, or else reference a `modifier_value_id` and a `variant_id`.' - description: Common ComplexRule properties. - meta: - title: Meta - type: object - properties: {} - description: Empty meta object; may be used later. - CustomFieldCollectionResponse: - description: '' - content: - application/json: - schema: - type: object - properties: - data: - type: array - items: - title: Custom Field - required: - - name - - value - type: object - properties: - id: - minimum: 1 - type: integer - description: |- - The unique numeric ID of the custom field; increments sequentially. - Read-Only - example: 6 - name: - maxLength: 250 - minLength: 1 - type: string - description: | - The name of the field, shown on the storefront, orders, etc. Required for /POST - example: ISBN - x-required: - - post - value: - maxLength: 250 - minLength: 1 - type: string - description: | - The name of the field, shown on the storefront, orders, etc. Required for /POST - example: '1234567890123' - x-required: - - post - description: 'Gets custom fields associated with a product. These allow you to specify additional information that will appear on the product’s page, such as a book’s ISBN or a DVD’s release date.' - meta: - $ref: '#/components/schemas/metaCollection_Full' - example: - data: - - name: Release year - value: '1987' - id: 1 - meta: - pagination: - total: 1 - count: 1 - per_page: 50 - current_page: 1 - total_pages: 1 - links: - previous: '?page=1&limit=50' - current: '?page=1&limit=50' - next: '?page=1&limit=50' - CustomFieldResponse: - description: '' - content: - application/json: - schema: - type: object - properties: - data: - title: Custom Field - required: - - name - - value - type: object - properties: - id: - minimum: 1 - type: integer - description: |- - The unique numeric ID of the custom field; increments sequentially. - Read-Only - example: 6 - name: - maxLength: 250 - minLength: 1 - type: string - description: | - The name of the field, shown on the storefront, orders, etc. Required for /POST - example: ISBN - x-required: - - post - value: - maxLength: 250 - minLength: 1 - type: string - description: | - The name of the field, shown on the storefront, orders, etc. Required for /POST - example: '1234567890123' - x-required: - - post - description: 'Gets custom fields associated with a product. These allow you to specify additional information that will appear on the product’s page, such as a book’s ISBN or a DVD’s release date.' - meta: - title: Meta - type: object - properties: {} - description: Empty meta object; may be used later. - example: - data: - name: Release Year - value: '1976' - id: 2 - meta: {} - Error404Response: - description: The requested category was not found. - content: - application/json: - schema: - $ref: '#/components/schemas/error_Base' - Error422Response: - description: |- - Unprocessable entity. - - Please verify if all requested products are assigned to the category. - - Please verify if all required fields are present in the request body and are filled with values correctly. - content: - application/json: - schema: - $ref: '#/components/schemas/error_Base' - General207Status: - description: 'Multi-status. Multiple operations have taken place and the status for each operation can be viewed in the body of the response. Typically indicates that a partial failure has occured, such as when a `POST` or `PUT` request is successful, but saving the URL or inventory data has failed.' - content: - application/json: - schema: - $ref: '#/components/schemas/error_Base' - MetafieldCollectionResponse: - description: '' - content: - application/json: - schema: - title: Meta Field Collection Response - type: object - properties: - data: - type: array - items: - title: Metafield - required: - - key - - namespace - - permission_set - - value - type: object - properties: - id: - type: integer - description: Unique ID of the *Metafield*. Read-Only. - readOnly: true - example: 6 - permission_set: - type: string - description: |- - Determines the visibility and writeability of the field by other API consumers. - - |Value|Description - |-|-| - |`app_only`|Private to the app that owns the field| - |`read`|Visible to other API consumers| - |`write`|Open for reading and writing by other API consumers| - |`read_and_sf_access`|Visible to other API consumers, including on storefront| - |`write_and_sf_access`|Open for reading and writing by other API consumers, including on storefront| - enum: - - app_only - - read - - write - - read_and_sf_access - - write_and_sf_access - x-required: - - post - namespace: - maxLength: 64 - minLength: 1 - type: string - description: | - Namespace for the metafield, for organizational purposes. This is set set by the developer. Required for POST. - example: Warehouse Locations - x-required: - - post - key: - maxLength: 64 - minLength: 1 - type: string - description: | - The name of the field, for example: `location_id`, `color`. Required for POST. - example: Location - x-required: - - post - value: - maxLength: 65535 - minLength: 1 - type: string - description: | - The value of the field, for example: `1`, `blue`. Required for POST. - example: 4HG - x-required: - - post - description: - maxLength: 255 - minLength: 0 - type: string - description: | - Description for the metafields. - example: Location in the warehouse - resource_type: - type: string - description: | - The type of resource with which the metafield is associated. - example: product - enum: - - category - - brand - - product - - variant - x-required: - - post - resource_id: - maximum: 10000000000 - minimum: 0 - type: integer - description: | - The ID for the resource with which the metafield is associated. - example: 111 - x-required: - - post - date_created: - type: string - description: | - Date and time of the metafield's creation. Read-Only. - readOnly: true - format: date-time - example: '2018-05-07T20:14:17+00:00' - date_modified: - type: string - description: | - Date and time when the metafield was last updated. Read-Only. - readOnly: true - format: date-time - example: '2018-05-07T20:14:17+00:00' - description: Common Metafield properties. - meta: - $ref: '#/components/schemas/metaCollection_Full' - example: - data: - - permission_set: app_only - namespace: Warehouse Locations - key: Location - value: 4HG - description: Location in the warehouse - resource_type: brand - resource_id: 111 - id: 6 - date_created: '1973-01-20T21:34:57.903Z' - date_modified: '1990-12-30T00:29:23.515Z' - - permission_set: read - namespace: Warehouse Locations - key: Location - value: 4HG - description: Location in the warehouse - resource_type: brand - resource_id: 111 - id: 6 - date_created: '1973-01-20T21:34:57.903Z' - date_modified: '1990-12-30T00:29:23.515Z' - - permission_set: app_only - namespace: Warehouse Locations - key: Location - value: 4HG - description: Location in the warehouse - resource_type: brand - resource_id: 111 - id: 6 - date_created: '1973-01-20T21:34:57.903Z' - date_modified: '1990-12-30T00:29:23.515Z' - meta: - pagination: - total: 3 - count: 3 - per_page: 50 - current_page: 1 - total_pages: 1 - links: - current: '?page=1&limit=50' - MetafieldResponse: - description: '' - content: - application/json: - schema: - title: Metafield Response - type: object - properties: - data: - title: Metafield - required: - - key - - namespace - - permission_set - - value - type: object - properties: - date_created: - type: string - description: | - Date and time of the metafield's creation. Read-Only. - readOnly: true - format: date-time - example: '2018-05-07T20:14:17+00:00' - date_modified: - type: string - description: | - Date and time when the metafield was last updated. Read-Only. - readOnly: true - format: date-time - example: '2018-05-07T20:14:17+00:00' - description: - maxLength: 255 - minLength: 0 - type: string - description: | - Description for the metafields. - example: Location in the warehouse - id: - type: integer - description: Unique ID of the *Metafield*. Read-Only. - readOnly: true - example: 6 - key: - maxLength: 64 - minLength: 1 - type: string - description: | - The name of the field, for example: `location_id`, `color`. Required for POST. - example: Location - x-required: - - post - namespace: - maxLength: 64 - minLength: 1 - type: string - description: | - Namespace for the metafield, for organizational purposes. This is set set by the developer. Required for POST. - example: Warehouse Locations - x-required: - - post - permission_set: - type: string - description: |- - Determines the visibility and writeability of the field by other API consumers. - - |Value|Description - |-|-| - |`app_only`|Private to the app that owns the field| - |`read`|Visible to other API consumers| - |`write`|Open for reading and writing by other API consumers| - |`read_and_sf_access`|Visible to other API consumers, including on storefront| - |`write_and_sf_access`|Open for reading and writing by other API consumers, including on storefront| - enum: - - app_only - - read - - write - - read_and_sf_access - - write_and_sf_access - x-required: - - post - resource_id: - maximum: 10000000000 - minimum: 0 - type: integer - description: | - The ID for the resource with which the metafield is associated. - example: 111 - x-required: - - post - resource_type: - type: string - description: | - The type of resource with which the metafield is associated. - example: product - enum: - - category - - brand - - product - - variant - x-required: - - post - value: - maxLength: 65535 - minLength: 1 - type: string - description: | - The value of the field, for example: `1`, `blue`. Required for POST. - example: 4HG - x-required: - - post - description: Common Metafield properties. - meta: - title: Meta - type: object - properties: {} - description: Empty meta object; may be used later. - example: - data: - date_created: '2021-08-06T19:15:35+00:00' - date_modified: '2021-08-06T19:15:35+00:00' - description: Where products are located - id: 4 - key: location_id - namespace: App Namespace - permission_set: app_only - resource_id: 137 - resource_type: product - value: 'Shelf 3, Bin 5' - meta: {} - ModifierCollectionResponse: - description: '' - content: - application/json: - schema: - title: Modifier Collection Response - type: object - properties: - data: - type: array - items: - title: Modifer - type: object - description: Product Modifier - allOf: - - title: Modifier Base - required: - - required - - type - type: object - properties: - type: - type: string - description: | - BigCommerce API, which determines how it will display on the storefront. Acceptable values: `date`, `checkbox`, `file`, `text`, `multi_line_text`, `numbers_only_text`, `radio_buttons`, `rectangles`, `dropdown`, `product_list`, `product_list_with_images`, `swatch`. Required in a /POST. - enum: - - date - - checkbox - - file - - text - - multi_line_text - - numbers_only_text - - radio_buttons - - rectangles - - dropdown - - product_list - - product_list_with_images - - swatch - x-required: - - post - required: - type: boolean - description: | - Whether or not this modifer is required or not at checkout. Required in a /POST. - x-required: - - post - sort_order: - type: integer - description: The order the modifiers display on the product detail page. - config: - title: Option Config - type: object - properties: - default_value: - type: string - description: | - (date, text, multi_line_text, numbers_only_text) The default value. Shown on a date option as an ISO-8601–formatted string, or on a text option as a string. - checked_by_default: - type: boolean - description: | - (checkbox) Flag for setting the checkbox to be checked by default. - checkbox_label: - type: string - description: | - (checkbox) Label displayed for the checkbox option. - date_limited: - type: boolean - description: | - (date) Flag to limit the dates allowed to be entered on a date option. - date_limit_mode: - type: string - description: | - (date) The type of limit that is allowed to be entered on a date option. - example: range - enum: - - earliest - - range - - latest - date_earliest_value: - type: string - description: | - (date) The earliest date allowed to be entered on the date option, as an ISO-8601 formatted string. - format: date - date_latest_value: - type: string - description: | - (date) The latest date allowed to be entered on the date option, as an ISO-8601 formatted string. - format: date - file_types_mode: - type: string - description: | - (file) The kind of restriction on the file types that can be uploaded with a file upload option. Values: `specific` - restricts uploads to particular file types; `all` - allows all file types. - example: specific - enum: - - specific - - all - file_types_supported: - type: array - description: | - (file) The type of files allowed to be uploaded if the `file_type_option` is set to `specific`. Values: - `images` - Allows upload of image MIME types (`bmp`, `gif`, `jpg`, `jpeg`, `jpe`, `jif`, `jfif`, `jfi`, `png`, `wbmp`, `xbm`, `tiff`). `documents` - Allows upload of document MIME types (`txt`, `pdf`, `rtf`, `doc`, `docx`, `xls`, `xlsx`, `accdb`, `mdb`, `one`, `pps`, `ppsx`, `ppt`, `pptx`, `pub`, `odt`, `ods`, `odp`, `odg`, `odf`). - `other` - Allows file types defined in the `file_types_other` array. - items: - type: string - example: 'images, documents, other' - file_types_other: - type: array - description: | - (file) A list of other file types allowed with the file upload option. - items: - type: string - example: pdf - file_max_size: - type: integer - description: | - (file) The maximum size for a file that can be used with the file upload option. This will still be limited by the server. - example: 5 - text_characters_limited: - type: boolean - description: | - (text, multi_line_text) Flag to validate the length of a text or multi-line text input. - text_min_length: - type: integer - description: | - (text, multi_line_text) The minimum length allowed for a text or multi-line text option. - example: 1 - text_max_length: - type: integer - description: | - (text, multi_line_text) The maximum length allowed for a text or multi line text option. - example: 55 - text_lines_limited: - type: boolean - description: | - (multi_line_text) Flag to validate the maximum number of lines allowed on a multi-line text input. - example: true - text_max_lines: - type: integer - description: | - (multi_line_text) The maximum number of lines allowed on a multi-line text input. - example: 4 - number_limited: - type: boolean - description: | - (numbers_only_text) Flag to limit the value of a number option. - example: true - number_limit_mode: - type: string - description: | - (numbers_only_text) The type of limit on values entered for a number option. - example: lowest - enum: - - lowest - - highest - - range - number_lowest_value: - type: number - description: | - (numbers_only_text) The lowest allowed value for a number option if `number_limited` is true. - example: 100 - number_highest_value: - type: number - description: | - (numbers_only_text) The highest allowed value for a number option if `number_limited` is true. - number_integers_only: - type: boolean - description: | - (numbers_only_text) Flag to limit the input on a number option to whole numbers only. - example: false - product_list_adjusts_inventory: - type: boolean - description: | - (product_list, product_list_with_images) Flag for automatically adjusting inventory on a product included in the list. - product_list_adjusts_pricing: - type: boolean - description: | - (product_list, product_list_with_images) Flag to add the optional product's price to the main product's price. - product_list_shipping_calc: - type: string - description: | - (product_list, product_list_with_images) How to factor the optional product's weight and package dimensions into the shipping quote. Values: `none` - don't adjust; `weight` - use shipping weight only; `package` - use weight and dimensions. - example: weight - enum: - - none - - weight - - package - description: The values for option config can vary based on the Modifier created. - option_values: - type: array - items: - title: Modifier Value - type: object - description: 'Part of Modifier Value Response ' - allOf: - - title: Modifier Value Base - type: object - allOf: - - title: Option Value Base - required: - - label - - sort_order - type: object - properties: - is_default: - type: boolean - description: | - The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. - example: false - label: - type: string - description: | - The text display identifying the value on the storefront. Required in a /POST. - example: Green - x-required: - - post - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the value will be displayed on the product page. Required in a /POST. - example: 0 - x-required: - - post - value_data: - type: object - properties: {} - description: | - Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. - description: Common Option Value properties. - - type: object - properties: - adjusters: - type: object - properties: - price: - title: Adjuster - type: object - properties: - adjuster: - type: string - description: | - The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - enum: - - relative - - percentage - x-nullable: true - adjuster_value: - type: number - description: | - The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. - example: 5 - description: Adjuster for Complex Rules. - weight: - title: Adjuster - type: object - properties: - adjuster: - type: string - description: | - The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - enum: - - relative - - percentage - x-nullable: true - adjuster_value: - type: number - description: | - The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. - example: 5 - description: Adjuster for Complex Rules. - image_url: - type: string - description: | - The URL for an image displayed on the storefront when the modifier value is selected.Limit of 8MB per file. - example: 'https://cdn8.bigcommerce.com/s-{{store_hash}}/products/184/images/445/naturalcanvascart2_1024x1024__92347__29648.1534344533.1280.1280.jpg?c=2' - purchasing_disabled: - type: object - properties: - status: - type: boolean - description: | - Flag for whether the modifier value disables purchasing when selected on the storefront. This can be used for temporarily disabling a particular modifier value. - message: - type: string - description: | - The message displayed on the storefront when the purchasing disabled status is `true`. - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the value; increments sequentially. - description: Common Modifier properties. - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the modifier; increments sequentially. - example: 12 - product_id: - type: integer - description: | - The unique numeric ID of the product to which the option belongs. - example: 77 - name: - type: string - description: | - The unique option name. Auto-generated from the display name, a timestamp, and the product ID. - example: Add-a-$5-Donation1535039590-191 - display_name: - type: string - description: | - The name of the option shown on the storefront. - example: Donation - meta: - $ref: '#/components/schemas/metaCollection_Full' - description: Modifier Collection Response return for /GET All Modifiers. - example: - data: - - id: 206 - product_id: 158 - name: Insurance - display_name: Insurace - type: checkbox - required: true - config: - checkbox_label: $5 for insurance - checked_by_default: false - option_values: - - id: 183 - option_id: 206 - label: 'Yes' - sort_order: 0 - value_data: - checked_value: true - is_default: false - adjusters: - price: {} - weight: {} - image_url: '' - purchasing_disabled: - status: false - message: '' - - id: 184 - option_id: 206 - label: 'No' - sort_order: 1 - value_data: - checked_value: false - is_default: true - adjusters: - price: {} - weight: {} - image_url: '' - purchasing_disabled: - status: false - message: '' - meta: - pagination: - total: 1 - count: 1 - per_page: 50 - current_page: 1 - total_pages: 1 - links: - current: '?page=1&limit=50' - ModifierResponse: - description: '' - content: - application/json: - schema: - title: Modifier Response - type: object - properties: - data: - title: Modifer - type: object - description: Product Modifier - allOf: - - title: Modifier Base - required: - - required - - type - type: object - properties: - type: - type: string - description: | - BigCommerce API, which determines how it will display on the storefront. Acceptable values: `date`, `checkbox`, `file`, `text`, `multi_line_text`, `numbers_only_text`, `radio_buttons`, `rectangles`, `dropdown`, `product_list`, `product_list_with_images`, `swatch`. Required in a /POST. - enum: - - date - - checkbox - - file - - text - - multi_line_text - - numbers_only_text - - radio_buttons - - rectangles - - dropdown - - product_list - - product_list_with_images - - swatch - x-required: - - post - required: - type: boolean - description: | - Whether or not this modifer is required or not at checkout. Required in a /POST. - x-required: - - post - sort_order: - type: integer - description: The order the modifiers display on the product detail page. - config: - title: Option Config - type: object - properties: - default_value: - type: string - description: | - (date, text, multi_line_text, numbers_only_text) The default value. Shown on a date option as an ISO-8601–formatted string, or on a text option as a string. - checked_by_default: - type: boolean - description: | - (checkbox) Flag for setting the checkbox to be checked by default. - checkbox_label: - type: string - description: | - (checkbox) Label displayed for the checkbox option. - date_limited: - type: boolean - description: | - (date) Flag to limit the dates allowed to be entered on a date option. - date_limit_mode: - type: string - description: | - (date) The type of limit that is allowed to be entered on a date option. - example: range - enum: - - earliest - - range - - latest - date_earliest_value: - type: string - description: | - (date) The earliest date allowed to be entered on the date option, as an ISO-8601 formatted string. - format: date - date_latest_value: - type: string - description: | - (date) The latest date allowed to be entered on the date option, as an ISO-8601 formatted string. - format: date - file_types_mode: - type: string - description: | - (file) The kind of restriction on the file types that can be uploaded with a file upload option. Values: `specific` - restricts uploads to particular file types; `all` - allows all file types. - example: specific - enum: - - specific - - all - file_types_supported: - type: array - description: | - (file) The type of files allowed to be uploaded if the `file_type_option` is set to `specific`. Values: - `images` - Allows upload of image MIME types (`bmp`, `gif`, `jpg`, `jpeg`, `jpe`, `jif`, `jfif`, `jfi`, `png`, `wbmp`, `xbm`, `tiff`). `documents` - Allows upload of document MIME types (`txt`, `pdf`, `rtf`, `doc`, `docx`, `xls`, `xlsx`, `accdb`, `mdb`, `one`, `pps`, `ppsx`, `ppt`, `pptx`, `pub`, `odt`, `ods`, `odp`, `odg`, `odf`). - `other` - Allows file types defined in the `file_types_other` array. - items: - type: string - example: 'images, documents, other' - file_types_other: - type: array - description: | - (file) A list of other file types allowed with the file upload option. - items: - type: string - example: pdf - file_max_size: - type: integer - description: | - (file) The maximum size for a file that can be used with the file upload option. This will still be limited by the server. - example: 5 - text_characters_limited: - type: boolean - description: | - (text, multi_line_text) Flag to validate the length of a text or multi-line text input. - text_min_length: - type: integer - description: | - (text, multi_line_text) The minimum length allowed for a text or multi-line text option. - example: 1 - text_max_length: - type: integer - description: | - (text, multi_line_text) The maximum length allowed for a text or multi line text option. - example: 55 - text_lines_limited: - type: boolean - description: | - (multi_line_text) Flag to validate the maximum number of lines allowed on a multi-line text input. - example: true - text_max_lines: - type: integer - description: | - (multi_line_text) The maximum number of lines allowed on a multi-line text input. - example: 4 - number_limited: - type: boolean - description: | - (numbers_only_text) Flag to limit the value of a number option. - example: true - number_limit_mode: - type: string - description: | - (numbers_only_text) The type of limit on values entered for a number option. - example: lowest - enum: - - lowest - - highest - - range - number_lowest_value: - type: number - description: | - (numbers_only_text) The lowest allowed value for a number option if `number_limited` is true. - example: 100 - number_highest_value: - type: number - description: | - (numbers_only_text) The highest allowed value for a number option if `number_limited` is true. - number_integers_only: - type: boolean - description: | - (numbers_only_text) Flag to limit the input on a number option to whole numbers only. - example: false - product_list_adjusts_inventory: - type: boolean - description: | - (product_list, product_list_with_images) Flag for automatically adjusting inventory on a product included in the list. - product_list_adjusts_pricing: - type: boolean - description: | - (product_list, product_list_with_images) Flag to add the optional product's price to the main product's price. - product_list_shipping_calc: - type: string - description: | - (product_list, product_list_with_images) How to factor the optional product's weight and package dimensions into the shipping quote. Values: `none` - don't adjust; `weight` - use shipping weight only; `package` - use weight and dimensions. - example: weight - enum: - - none - - weight - - package - description: The values for option config can vary based on the Modifier created. - option_values: - type: array - items: - title: Modifier Value - type: object - description: 'Part of Modifier Value Response ' - allOf: - - title: Modifier Value Base - type: object - allOf: - - title: Option Value Base - required: - - label - - sort_order - type: object - properties: - is_default: - type: boolean - description: | - The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. - example: false - label: - type: string - description: | - The text display identifying the value on the storefront. Required in a /POST. - example: Green - x-required: - - post - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the value will be displayed on the product page. Required in a /POST. - example: 0 - x-required: - - post - value_data: - type: object - properties: {} - description: | - Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. - description: Common Option Value properties. - - type: object - properties: - adjusters: - type: object - properties: - price: - title: Adjuster - type: object - properties: - adjuster: - type: string - description: | - The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - enum: - - relative - - percentage - x-nullable: true - adjuster_value: - type: number - description: | - The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. - example: 5 - description: Adjuster for Complex Rules. - weight: - title: Adjuster - type: object - properties: - adjuster: - type: string - description: | - The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - enum: - - relative - - percentage - x-nullable: true - adjuster_value: - type: number - description: | - The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. - example: 5 - description: Adjuster for Complex Rules. - image_url: - type: string - description: | - The URL for an image displayed on the storefront when the modifier value is selected.Limit of 8MB per file. - example: 'https://cdn8.bigcommerce.com/s-{{store_hash}}/products/184/images/445/naturalcanvascart2_1024x1024__92347__29648.1534344533.1280.1280.jpg?c=2' - purchasing_disabled: - type: object - properties: - status: - type: boolean - description: | - Flag for whether the modifier value disables purchasing when selected on the storefront. This can be used for temporarily disabling a particular modifier value. - message: - type: string - description: | - The message displayed on the storefront when the purchasing disabled status is `true`. - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the value; increments sequentially. - description: Common Modifier properties. - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the modifier; increments sequentially. - example: 12 - product_id: - type: integer - description: | - The unique numeric ID of the product to which the option belongs. - example: 77 - name: - type: string - description: | - The unique option name. Auto-generated from the display name, a timestamp, and the product ID. - example: Add-a-$5-Donation1535039590-191 - display_name: - type: string - description: | - The name of the option shown on the storefront. - example: Donation - meta: - title: Meta - type: object - properties: {} - description: Empty meta object; may be used later. - ModifierValueCollectionResponse: - description: '' - content: - application/json: - schema: - title: Modifier Value Collection Response - type: object - properties: - data: - type: array - items: - title: Modifier Value - type: object - description: 'Part of Modifier Value Response ' - allOf: - - title: Modifier Value Base - type: object - allOf: - - title: Option Value Base - required: - - label - - sort_order - type: object - properties: - is_default: - type: boolean - description: | - The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. - example: false - label: - type: string - description: | - The text display identifying the value on the storefront. Required in a /POST. - example: Green - x-required: - - post - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the value will be displayed on the product page. Required in a /POST. - example: 0 - x-required: - - post - value_data: - type: object - properties: {} - description: | - Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. - description: Common Option Value properties. - - type: object - properties: - adjusters: - type: object - properties: - price: - title: Adjuster - type: object - properties: - adjuster: - type: string - description: | - The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - enum: - - relative - - percentage - x-nullable: true - adjuster_value: - type: number - description: | - The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. - example: 5 - description: Adjuster for Complex Rules. - weight: - title: Adjuster - type: object - properties: - adjuster: - type: string - description: | - The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - enum: - - relative - - percentage - x-nullable: true - adjuster_value: - type: number - description: | - The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. - example: 5 - description: Adjuster for Complex Rules. - image_url: - type: string - description: | - The URL for an image displayed on the storefront when the modifier value is selected.Limit of 8MB per file. - example: 'https://cdn8.bigcommerce.com/s-{{store_hash}}/products/184/images/445/naturalcanvascart2_1024x1024__92347__29648.1534344533.1280.1280.jpg?c=2' - purchasing_disabled: - type: object - properties: - status: - type: boolean - description: | - Flag for whether the modifier value disables purchasing when selected on the storefront. This can be used for temporarily disabling a particular modifier value. - message: - type: string - description: | - The message displayed on the storefront when the purchasing disabled status is `true`. - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the value; increments sequentially. - meta: - $ref: '#/components/schemas/metaCollection_Full' - description: Returns for GET All Modifier Values on a Product - example: - data: - - id: 190 - option_id: 222 - label: 'Yes' - sort_order: 0 - value_data: - checked_value: true - is_default: false - adjusters: - price: - adjuster: relative - adjuster_value: 5 - weight: {} - image_url: '' - purchasing_disabled: - status: false - message: '' - - id: 191 - option_id: 222 - label: 'No' - sort_order: 1 - value_data: - checked_value: false - is_default: true - adjusters: - price: {} - weight: {} - image_url: '' - purchasing_disabled: - status: false - message: '' - meta: - pagination: - total: 2 - count: 2 - per_page: 50 - current_page: 1 - total_pages: 1 - links: - current: '?page=1&limit=50' - ModifierValueResponse: - description: '' - content: - application/json: - schema: - title: Modifier Value Response - type: object - properties: - data: - title: Modifier Value - type: object - description: 'Part of Modifier Value Response ' - allOf: - - title: Modifier Value Base - type: object - allOf: - - title: Option Value Base - required: - - label - - sort_order - type: object - properties: - is_default: - type: boolean - description: | - The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. - example: false - label: - type: string - description: | - The text display identifying the value on the storefront. Required in a /POST. - example: Green - x-required: - - post - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the value will be displayed on the product page. Required in a /POST. - example: 0 - x-required: - - post - value_data: - type: object - properties: {} - description: | - Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. - description: Common Option Value properties. - - type: object - properties: - adjusters: - type: object - properties: - price: - title: Adjuster - type: object - properties: - adjuster: - type: string - description: | - The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - enum: - - relative - - percentage - x-nullable: true - adjuster_value: - type: number - description: | - The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. - example: 5 - description: Adjuster for Complex Rules. - weight: - title: Adjuster - type: object - properties: - adjuster: - type: string - description: | - The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. - enum: - - relative - - percentage - x-nullable: true - adjuster_value: - type: number - description: | - The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. - example: 5 - description: Adjuster for Complex Rules. - image_url: - type: string - description: | - The URL for an image displayed on the storefront when the modifier value is selected.Limit of 8MB per file. - example: 'https://cdn8.bigcommerce.com/s-{{store_hash}}/products/184/images/445/naturalcanvascart2_1024x1024__92347__29648.1534344533.1280.1280.jpg?c=2' - purchasing_disabled: - type: object - properties: - status: - type: boolean - description: | - Flag for whether the modifier value disables purchasing when selected on the storefront. This can be used for temporarily disabling a particular modifier value. - message: - type: string - description: | - The message displayed on the storefront when the purchasing disabled status is `true`. - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the value; increments sequentially. - meta: - title: Meta - type: object - properties: {} - description: Empty meta object; may be used later. - example: - data: - id: 190 - option_id: 222 - label: 'Yes' - sort_order: 0 - value_data: {} - is_default: false - adjusters: - price: - adjuster: relative - adjuster_value: 5 - weight: {} - image_url: '' - purchasing_disabled: - status: false - message: '' - meta: {} - OptionCollectionResponse: - description: '' - content: - application/json: - schema: - title: Option Collection Response - type: object - properties: - data: - type: array - items: - title: Option - type: object - allOf: - - title: Option Base - type: object - properties: - id: - type: integer - description: | - The unique numerical ID of the option, increments sequentially. - example: 55 - x-nullable: true - product_id: - type: integer - description: | - The unique numerical ID of the product to which the option belongs. - example: 4 - x-required: - - post - - put - display_name: - maxLength: 255 - minLength: 1 - type: string - description: | - The name of the option shown on the storefront. - example: Add-a-$5-Donation1535042499-187 - x-required: - - post - - put - type: - type: string - description: | - The type of option, which determines how it will display on the storefront. Acceptable values: `radio_buttons`, `rectangles`, `dropdown`, `product_list`, `product_list_with_images`, `swatch`. For reference, the former v2 API values are: RB = radio_buttons, RT = rectangles, S = dropdown, P = product_list, PI = product_list_with_images, CS = swatch. - enum: - - radio_buttons - - rectangles - - dropdown - - product_list - - product_list_with_images - - swatch - x-required: - - post - - put - config: - title: Option Config - type: object - properties: - default_value: - type: string - description: | - (date, text, multi_line_text, numbers_only_text) The default value. Shown on a date option as an ISO-8601–formatted string, or on a text option as a string. - checked_by_default: - type: boolean - description: | - (checkbox) Flag for setting the checkbox to be checked by default. - checkbox_label: - type: string - description: | - (checkbox) Label displayed for the checkbox option. - date_limited: - type: boolean - description: | - (date) Flag to limit the dates allowed to be entered on a date option. - date_limit_mode: - type: string - description: | - (date) The type of limit that is allowed to be entered on a date option. - example: range - enum: - - earliest - - range - - latest - date_earliest_value: - type: string - description: | - (date) The earliest date allowed to be entered on the date option, as an ISO-8601 formatted string. - format: date - date_latest_value: - type: string - description: | - (date) The latest date allowed to be entered on the date option, as an ISO-8601 formatted string. - format: date - file_types_mode: - type: string - description: | - (file) The kind of restriction on the file types that can be uploaded with a file upload option. Values: `specific` - restricts uploads to particular file types; `all` - allows all file types. - example: specific - enum: - - specific - - all - file_types_supported: - type: array - description: | - (file) The type of files allowed to be uploaded if the `file_type_option` is set to `specific`. Values: - `images` - Allows upload of image MIME types (`bmp`, `gif`, `jpg`, `jpeg`, `jpe`, `jif`, `jfif`, `jfi`, `png`, `wbmp`, `xbm`, `tiff`). `documents` - Allows upload of document MIME types (`txt`, `pdf`, `rtf`, `doc`, `docx`, `xls`, `xlsx`, `accdb`, `mdb`, `one`, `pps`, `ppsx`, `ppt`, `pptx`, `pub`, `odt`, `ods`, `odp`, `odg`, `odf`). - `other` - Allows file types defined in the `file_types_other` array. - items: - type: string - example: 'images, documents, other' - file_types_other: - type: array - description: | - (file) A list of other file types allowed with the file upload option. - items: - type: string - example: pdf - file_max_size: - type: integer - description: | - (file) The maximum size for a file that can be used with the file upload option. This will still be limited by the server. - example: 5 - text_characters_limited: - type: boolean - description: | - (text, multi_line_text) Flag to validate the length of a text or multi-line text input. - text_min_length: - type: integer - description: | - (text, multi_line_text) The minimum length allowed for a text or multi-line text option. - example: 1 - text_max_length: - type: integer - description: | - (text, multi_line_text) The maximum length allowed for a text or multi line text option. - example: 55 - text_lines_limited: - type: boolean - description: | - (multi_line_text) Flag to validate the maximum number of lines allowed on a multi-line text input. - example: true - text_max_lines: - type: integer - description: | - (multi_line_text) The maximum number of lines allowed on a multi-line text input. - example: 4 - number_limited: - type: boolean - description: | - (numbers_only_text) Flag to limit the value of a number option. - example: true - number_limit_mode: - type: string - description: | - (numbers_only_text) The type of limit on values entered for a number option. - example: lowest - enum: - - lowest - - highest - - range - number_lowest_value: - type: number - description: | - (numbers_only_text) The lowest allowed value for a number option if `number_limited` is true. - example: 100 - number_highest_value: - type: number - description: | - (numbers_only_text) The highest allowed value for a number option if `number_limited` is true. - number_integers_only: - type: boolean - description: | - (numbers_only_text) Flag to limit the input on a number option to whole numbers only. - example: false - product_list_adjusts_inventory: - type: boolean - description: | - (product_list, product_list_with_images) Flag for automatically adjusting inventory on a product included in the list. - product_list_adjusts_pricing: - type: boolean - description: | - (product_list, product_list_with_images) Flag to add the optional product's price to the main product's price. - product_list_shipping_calc: - type: string - description: | - (product_list, product_list_with_images) How to factor the optional product's weight and package dimensions into the shipping quote. Values: `none` - don't adjust; `weight` - use shipping weight only; `package` - use weight and dimensions. - example: weight - enum: - - none - - weight - - package - description: The values for option config can vary based on the Modifier created. - sort_order: - type: integer - description: 'Order in which the option is displayed on the storefront. ' - example: 1 - option_values: - minItems: 1 - type: array - items: - title: Option Value - type: object - allOf: - - title: Option Value Base - required: - - label - - sort_order - type: object - properties: - is_default: - type: boolean - description: | - The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. - example: false - label: - type: string - description: | - The text display identifying the value on the storefront. Required in a /POST. - example: Green - x-required: - - post - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the value will be displayed on the product page. Required in a /POST. - example: 0 - x-required: - - post - value_data: - type: object - properties: {} - description: | - Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. - description: Common Option Value properties. - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the value; increments sequentially. - x-required: - - post - - put - image_url: - type: string - description: Publicly available image url - description: Common Option properties. - - type: object - properties: - name: - type: string - description: | - The unique option name, auto-generated from the display name, a timestamp, and the product ID. - example: Add-a-$5-Donation1535042499-187 - meta: - $ref: '#/components/schemas/metaCollection_Full' - description: Get all product options - example: - data: - - id: 220 - product_id: 192 - name: Color (Colors only) - display_name: Color - type: swatch - sort_order: 0 - option_values: - - id: 174 - label: Beige - sort_order: 1 - value_data: - colors: - - '#FAFAEB' - is_default: false - - id: 175 - label: Grey - sort_order: 2 - value_data: - colors: - - '#BDBDBD' - is_default: false - - id: 176 - label: Black - sort_order: 3 - value_data: - colors: - - '#000000' - is_default: false - - id: 189 - label: Black-Walnut - sort_order: 4 - value_data: - colors: - - '#e80ee8' - is_default: false - config: {} - meta: - pagination: - total: 1 - count: 1 - per_page: 50 - current_page: 1 - total_pages: 1 - links: - current: '?page=1&limit=50' - OptionResponse: - description: '' - content: - application/json: - schema: - title: Option Response - type: object - properties: - data: - title: Option - type: object - allOf: - - title: Option Base - type: object - properties: - id: - type: integer - description: | - The unique numerical ID of the option, increments sequentially. - example: 55 - x-nullable: true - product_id: - type: integer - description: | - The unique numerical ID of the product to which the option belongs. - example: 4 - x-required: - - post - - put - display_name: - maxLength: 255 - minLength: 1 - type: string - description: | - The name of the option shown on the storefront. - example: Add-a-$5-Donation1535042499-187 - x-required: - - post - - put - type: - type: string - description: | - The type of option, which determines how it will display on the storefront. Acceptable values: `radio_buttons`, `rectangles`, `dropdown`, `product_list`, `product_list_with_images`, `swatch`. For reference, the former v2 API values are: RB = radio_buttons, RT = rectangles, S = dropdown, P = product_list, PI = product_list_with_images, CS = swatch. - enum: - - radio_buttons - - rectangles - - dropdown - - product_list - - product_list_with_images - - swatch - x-required: - - post - - put - config: - title: Option Config - type: object - properties: - default_value: - type: string - description: | - (date, text, multi_line_text, numbers_only_text) The default value. Shown on a date option as an ISO-8601–formatted string, or on a text option as a string. - checked_by_default: - type: boolean - description: | - (checkbox) Flag for setting the checkbox to be checked by default. - checkbox_label: - type: string - description: | - (checkbox) Label displayed for the checkbox option. - date_limited: - type: boolean - description: | - (date) Flag to limit the dates allowed to be entered on a date option. - date_limit_mode: - type: string - description: | - (date) The type of limit that is allowed to be entered on a date option. - example: range - enum: - - earliest - - range - - latest - date_earliest_value: - type: string - description: | - (date) The earliest date allowed to be entered on the date option, as an ISO-8601 formatted string. - format: date - date_latest_value: - type: string - description: | - (date) The latest date allowed to be entered on the date option, as an ISO-8601 formatted string. - format: date - file_types_mode: - type: string - description: | - (file) The kind of restriction on the file types that can be uploaded with a file upload option. Values: `specific` - restricts uploads to particular file types; `all` - allows all file types. - example: specific - enum: - - specific - - all - file_types_supported: - type: array - description: | - (file) The type of files allowed to be uploaded if the `file_type_option` is set to `specific`. Values: - `images` - Allows upload of image MIME types (`bmp`, `gif`, `jpg`, `jpeg`, `jpe`, `jif`, `jfif`, `jfi`, `png`, `wbmp`, `xbm`, `tiff`). `documents` - Allows upload of document MIME types (`txt`, `pdf`, `rtf`, `doc`, `docx`, `xls`, `xlsx`, `accdb`, `mdb`, `one`, `pps`, `ppsx`, `ppt`, `pptx`, `pub`, `odt`, `ods`, `odp`, `odg`, `odf`). - `other` - Allows file types defined in the `file_types_other` array. - items: - type: string - example: 'images, documents, other' - file_types_other: - type: array - description: | - (file) A list of other file types allowed with the file upload option. - items: - type: string - example: pdf - file_max_size: - type: integer - description: | - (file) The maximum size for a file that can be used with the file upload option. This will still be limited by the server. - example: 5 - text_characters_limited: - type: boolean - description: | - (text, multi_line_text) Flag to validate the length of a text or multi-line text input. - text_min_length: - type: integer - description: | - (text, multi_line_text) The minimum length allowed for a text or multi-line text option. - example: 1 - text_max_length: - type: integer - description: | - (text, multi_line_text) The maximum length allowed for a text or multi line text option. - example: 55 - text_lines_limited: - type: boolean - description: | - (multi_line_text) Flag to validate the maximum number of lines allowed on a multi-line text input. - example: true - text_max_lines: - type: integer - description: | - (multi_line_text) The maximum number of lines allowed on a multi-line text input. - example: 4 - number_limited: - type: boolean - description: | - (numbers_only_text) Flag to limit the value of a number option. - example: true - number_limit_mode: - type: string - description: | - (numbers_only_text) The type of limit on values entered for a number option. - example: lowest - enum: - - lowest - - highest - - range - number_lowest_value: - type: number - description: | - (numbers_only_text) The lowest allowed value for a number option if `number_limited` is true. - example: 100 - number_highest_value: - type: number - description: | - (numbers_only_text) The highest allowed value for a number option if `number_limited` is true. - number_integers_only: - type: boolean - description: | - (numbers_only_text) Flag to limit the input on a number option to whole numbers only. - example: false - product_list_adjusts_inventory: - type: boolean - description: | - (product_list, product_list_with_images) Flag for automatically adjusting inventory on a product included in the list. - product_list_adjusts_pricing: - type: boolean - description: | - (product_list, product_list_with_images) Flag to add the optional product's price to the main product's price. - product_list_shipping_calc: - type: string - description: | - (product_list, product_list_with_images) How to factor the optional product's weight and package dimensions into the shipping quote. Values: `none` - don't adjust; `weight` - use shipping weight only; `package` - use weight and dimensions. - example: weight - enum: - - none - - weight - - package - description: The values for option config can vary based on the Modifier created. - sort_order: - type: integer - description: 'Order in which the option is displayed on the storefront. ' - example: 1 - option_values: - minItems: 1 - type: array - items: - title: Option Value - type: object - allOf: - - title: Option Value Base - required: - - label - - sort_order - type: object - properties: - is_default: - type: boolean - description: | - The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. - example: false - label: - type: string - description: | - The text display identifying the value on the storefront. Required in a /POST. - example: Green - x-required: - - post - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the value will be displayed on the product page. Required in a /POST. - example: 0 - x-required: - - post - value_data: - type: object - properties: {} - description: | - Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. - description: Common Option Value properties. - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the value; increments sequentially. - x-required: - - post - - put - image_url: - type: string - description: Publicly available image url - description: Common Option properties. - - type: object - properties: - name: - type: string - description: | - The unique option name, auto-generated from the display name, a timestamp, and the product ID. - example: Add-a-$5-Donation1535042499-187 - meta: - title: Meta - type: object - properties: {} - description: Empty meta object; may be used later. - example: - data: - id: 220 - product_id: 192 - name: Color (Colors only) - display_name: Color - type: swatch - sort_order: 0 - option_values: - - id: 174 - label: Beige - sort_order: 1 - value_data: - colors: - - '#FAFAEB' - is_default: false - - id: 175 - label: Grey - sort_order: 2 - value_data: - colors: - - '#BDBDBD' - is_default: false - - id: 176 - label: Black - sort_order: 3 - value_data: - colors: - - '#000000' - is_default: false - - id: 189 - label: Black-Walnut - sort_order: 4 - value_data: - colors: - - '#e80ee8' - is_default: false - config: {} - meta: {} - OptionValueCollectionResponse: - description: '' - content: - application/json: - schema: - title: Option Value Collection Response - type: object - properties: - data: - type: array - items: - title: Option Value - type: object - allOf: - - title: Option Value Base - required: - - label - - sort_order - type: object - properties: - is_default: - type: boolean - description: | - The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. - example: false - label: - type: string - description: | - The text display identifying the value on the storefront. Required in a /POST. - example: Green - x-required: - - post - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the value will be displayed on the product page. Required in a /POST. - example: 0 - x-required: - - post - value_data: - type: object - properties: {} - description: | - Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. - description: Common Option Value properties. - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the value; increments sequentially. - meta: - $ref: '#/components/schemas/metaCollection_Full' - description: Get Option Values response. - example: - data: - - id: 174 - label: Beige - sort_order: 1 - value_data: - colors: - - '#FAFAEB' - is_default: false - - id: 175 - label: Grey - sort_order: 2 - value_data: - colors: - - '#BDBDBD' - is_default: false - - id: 176 - label: Black - sort_order: 3 - value_data: - colors: - - '#000000' - is_default: false - - id: 189 - label: Black-Walnut - sort_order: 4 - value_data: - colors: - - '#e80ee8' - is_default: false - meta: - pagination: - total: 4 - count: 4 - per_page: 50 - current_page: 1 - total_pages: 1 - links: - current: '?page=1&limit=50' - OptionValueResponse: - description: '' - content: - application/json: - schema: - title: Option Value Response - type: object - properties: - data: - title: Option Value - type: object - allOf: - - title: Option Value Base - required: - - label - - sort_order - type: object - properties: - is_default: - type: boolean - description: | - The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. - example: false - label: - type: string - description: | - The text display identifying the value on the storefront. Required in a /POST. - example: Green - x-required: - - post - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the value will be displayed on the product page. Required in a /POST. - example: 0 - x-required: - - post - value_data: - type: object - properties: {} - description: | - Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. - description: Common Option Value properties. - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the value; increments sequentially. - meta: - title: Meta - type: object - properties: {} - description: Empty meta object; may be used later. - example: - data: - id: 44 - label: Pick a color - sort_order: 9 - value_data: - colors: - - '#123c91, #FFFF00, #397a44' - is_default: false - ProductCollectionResponse: - description: '' - content: - application/json: - schema: - type: object - properties: - data: - type: array - items: - $ref: '#/components/schemas/product_Full' - meta: - $ref: '#/components/schemas/metaCollection_Full' - ProductImageCollectionResponse: - description: '' - content: - application/json: - schema: - title: Product Image Collection Response - type: object - properties: - data: - type: array - items: - title: Product Image - type: object - allOf: - - title: Product Image Base - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the image; increments sequentially. - product_id: - type: integer - description: | - The unique numeric identifier for the product with which the image is associated. - image_file: - type: string - description: | - The local path to the original image file uploaded to BigCommerce. - url_zoom: - type: string - description: | - The zoom URL for this image. By default, this is used as the zoom image on product pages when zoom images are enabled. - url_standard: - type: string - description: | - The standard URL for this image. By default, this is used for product-page images. - url_thumbnail: - type: string - description: | - The thumbnail URL for this image. By default, this is the image size used on the category page and in side panels. - url_tiny: - type: string - description: | - The tiny URL for this image. By default, this is the image size used for thumbnails beneath the product image on a product page. - date_modified: - type: string - description: | - The date on which the product image was modified. - format: date-time - is_thumbnail: - type: boolean - description: | - Flag for identifying whether the image is used as the product's thumbnail. - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the image will be displayed on the product page. Higher integers give the image a lower priority. When updating, if the image is given a lower priority, all images with a `sort_order` the same as or greater than the image's new `sort_order` value will have their `sort_order`s reordered. - description: - type: string - description: | - The description for the image. - description: Common ProductImage properties. - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the image; increments sequentially. - product_id: - type: integer - description: | - The unique numeric identifier for the product with which the image is associated. - image_file: - type: string - description: | - The local path to the original image file uploaded to BigCommerce. Use image_url when creating a product. - url_zoom: - type: string - description: | - The zoom URL for this image. By default, this is used as the zoom image on product pages when zoom images are enabled. - url_standard: - type: string - description: | - The standard URL for this image. By default, this is used for product-page images. - url_thumbnail: - type: string - description: | - The thumbnail URL for this image. By default, this is the image size used on the category page and in side panels. - url_tiny: - type: string - description: | - The tiny URL for this image. By default, this is the image size used for thumbnails beneath the product image on a product page. - date_modified: - type: string - description: | - The date on which the product image was modified. - format: date-time - image_url: - type: string - description: |- - Publically available URL. - Use the image_url when creating a product. - example: 'https://upload.wikimedia.org/wikipedia/commons/7/7f/Anglel_Bless_Legendary_Hills_1_m%C4%9Bs%C3%ADc_st%C3%A1%C5%99%C3%AD.jpg' - meta: - $ref: '#/components/schemas/metaCollection_Full' - description: | - Response payload for the BigCommerce API. - example: - data: - - id: 382 - product_id: 158 - is_thumbnail: true - sort_order: 0 - description: '' - image_file: a/521/foglinenbeigestripetowel1b_1024x1024__83011__60806.jpg - url_zoom: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/382/foglinenbeigestripetowel1b_1024x1024__83011__60806.1534344511.1280.1280.jpg?c=2' - url_standard: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/382/foglinenbeigestripetowel1b_1024x1024__83011__60806.1534344511.560.850.jpg?c=2' - url_thumbnail: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/382/foglinenbeigestripetowel1b_1024x1024__83011__60806.1534344511.330.500.jpg?c=2' - url_tiny: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/382/foglinenbeigestripetowel1b_1024x1024__83011__60806.1534344511.66.100.jpg?c=2' - date_modified: '2018-08-15T14:48:31+00:00' - - id: 383 - product_id: 158 - is_thumbnail: false - sort_order: 0 - description: '' - image_file: k/050/foglinenbeigestripetowel2b_1024x1024__16082__46564.jpg - url_zoom: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/383/foglinenbeigestripetowel2b_1024x1024__16082__46564.1534344511.1280.1280.jpg?c=2' - url_standard: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/383/foglinenbeigestripetowel2b_1024x1024__16082__46564.1534344511.560.850.jpg?c=2' - url_thumbnail: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/383/foglinenbeigestripetowel2b_1024x1024__16082__46564.1534344511.330.500.jpg?c=2' - url_tiny: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/383/foglinenbeigestripetowel2b_1024x1024__16082__46564.1534344511.66.100.jpg?c=2' - date_modified: '2018-08-15T14:48:31+00:00' - meta: - pagination: - total: 2 - count: 2 - per_page: 50 - current_page: 1 - total_pages: 1 - links: - current: '?page=1&limit=50' - ProductImageResponse: - description: '' - content: - application/json: - schema: - title: Product Image Response - type: object - properties: - data: - title: Product Image - type: object - allOf: - - title: Product Image Base - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the image; increments sequentially. - product_id: - type: integer - description: | - The unique numeric identifier for the product with which the image is associated. - image_file: - type: string - description: | - The local path to the original image file uploaded to BigCommerce. - url_zoom: - type: string - description: | - The zoom URL for this image. By default, this is used as the zoom image on product pages when zoom images are enabled. - url_standard: - type: string - description: | - The standard URL for this image. By default, this is used for product-page images. - url_thumbnail: - type: string - description: | - The thumbnail URL for this image. By default, this is the image size used on the category page and in side panels. - url_tiny: - type: string - description: | - The tiny URL for this image. By default, this is the image size used for thumbnails beneath the product image on a product page. - date_modified: - type: string - description: | - The date on which the product image was modified. - format: date-time - is_thumbnail: - type: boolean - description: | - Flag for identifying whether the image is used as the product's thumbnail. - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the image will be displayed on the product page. Higher integers give the image a lower priority. When updating, if the image is given a lower priority, all images with a `sort_order` the same as or greater than the image's new `sort_order` value will have their `sort_order`s reordered. - description: - type: string - description: | - The description for the image. - description: Common ProductImage properties. - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the image; increments sequentially. - product_id: - type: integer - description: | - The unique numeric identifier for the product with which the image is associated. - image_file: - type: string - description: | - The local path to the original image file uploaded to BigCommerce. Use image_url when creating a product. - url_zoom: - type: string - description: | - The zoom URL for this image. By default, this is used as the zoom image on product pages when zoom images are enabled. - url_standard: - type: string - description: | - The standard URL for this image. By default, this is used for product-page images. - url_thumbnail: - type: string - description: | - The thumbnail URL for this image. By default, this is the image size used on the category page and in side panels. - url_tiny: - type: string - description: | - The tiny URL for this image. By default, this is the image size used for thumbnails beneath the product image on a product page. - date_modified: - type: string - description: | - The date on which the product image was modified. - format: date-time - image_url: - type: string - description: |- - Publically available URL. - Use the image_url when creating a product. - example: 'https://upload.wikimedia.org/wikipedia/commons/7/7f/Anglel_Bless_Legendary_Hills_1_m%C4%9Bs%C3%ADc_st%C3%A1%C5%99%C3%AD.jpg' - meta: - title: Meta - type: object - properties: {} - description: Empty meta object; may be used later. - description: | - Response payload for the BigCommerce API. - example: - data: - id: 485 - product_id: 158 - is_thumbnail: false - sort_order: 1 - description: '' - image_file: o/381/product-image__98178.png - url_zoom: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/485/product-image__98178.1536854227.1280.1280.png?c=2' - url_standard: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/485/product-image__98178.1536854227.560.850.png?c=2' - url_thumbnail: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/485/product-image__98178.1536854227.330.500.png?c=2' - url_tiny: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/485/product-image__98178.1536854227.66.100.png?c=2' - date_modified: '2018-09-13T15:57:07+00:00' - meta: {} - ProductResponse: - description: '' - content: - application/json: - schema: - title: Product Response - type: object - properties: - data: - $ref: '#/components/schemas/product_Full' - meta: - $ref: '#/components/schemas/metaEmpty_Full' - example-1: - example: - name: Smith Journal 13 - type: physical - sku: SM-13 - description: '<p><span>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vel metus ac est egestas porta sed quis erat. Integer id nulla massa. Proin vitae enim nisi. Praesent non dignissim nulla. Nulla mattis id massa ac pharetra. Mauris et nisi in dolor aliquam sodales. Aliquam dui nisl, dictum quis leo sit amet, rutrum volutpat metus. Curabitur libero nunc, interdum ac libero non, tristique porttitor metus. Ut non dignissim lorem, in vestibulum leo. Vivamus sodales quis turpis eget.</span></p>' - weight: 0 - width: 0 - depth: 0 - height: 0 - price: 0 - cost_price: 0 - retail_price: 0 - sale_price: 0 - map_price: 0 - tax_class_id: 0 - product_tax_code: string - categories: - - 0 - brand_id: 0 - inventory_level: 0 - inventory_warning_level: 0 - inventory_tracking: none - fixed_cost_shipping_price: 0 - is_free_shipping: true - is_visible: true - is_featured: true - related_products: - - 0 - warranty: string - bin_picking_number: string - layout_file: string - upc: string - search_keywords: string - availability: available - availability_description: string - gift_wrapping_options_type: any - gift_wrapping_options_list: - - 0 - sort_order: -2147483648 - condition: New - is_condition_shown: true - order_quantity_minimum: 0 - order_quantity_maximum: 0 - page_title: string - meta_keywords: - - string - meta_description: string - view_count: 0 - preorder_release_date: '2019-08-24T14:15:22+00:00' - preorder_message: string - is_preorder_only: true - is_price_hidden: true - price_hidden_label: string - custom_url: - url: string - is_customized: true - open_graph_type: product - open_graph_title: string - open_graph_description: string - open_graph_use_meta_description: true - open_graph_use_product_name: true - open_graph_use_image: true - brand_name or brand_id: Common Good - gtin: string - mpn: string - reviews_rating_sum: 3.2 - reviews_count: 4 - total_sold: 80 - custom_fields: - - id: 6 - name: ISBN - value: '1234567890123' - bulk_pricing_rules: - - id: 0 - quantity_min: 10 - quantity_max: 50 - type: price - amount: 10 - images: - - image_file: string - is_thumbnail: true - sort_order: -2147483648 - description: string - image_url: string - id: 0 - product_id: 0 - url_zoom: string - url_standard: string - url_thumbnail: string - url_tiny: string - date_modified: '2019-08-24T14:15:22+00:00' - videos: - - title: string - description: string - sort_order: -2147483648 - type: youtube - video_id: string - id: 0 - product_id: 0 - length: string - date_created: '2018-08-15T14:49:05+00:00' - date_modified: '2018-08-24T14:41:00+00:00' - id: 1 - base_variant_id: 0 - calculated_price: 0 - options: - - id: 55 - product_id: 4 - display_name: Add-a-$5-Donation1535042499-187 - type: radio_buttons - config: - default_value: string - checked_by_default: true - checkbox_label: string - date_limited: true - date_limit_mode: range - date_earliest_value: '2019-08-24T00:00:00+00:00' - date_latest_value: '2019-08-24T00:00:00+00:00' - file_types_mode: specific - file_types_supported: - - 'images, documents, other' - file_types_other: - - pdf - file_max_size: 5 - text_characters_limited: true - text_min_length: 1 - text_max_length: 55 - text_lines_limited: true - text_max_lines: 4 - number_limited: true - number_limit_mode: lowest - number_lowest_value: 100 - number_highest_value: 0 - number_integers_only: false - product_list_adjusts_inventory: true - product_list_adjusts_pricing: true - product_list_shipping_calc: weight - sort_order: 1 - option_values: - is_default: false - label: Green - sort_order: 0 - value_data: {} - id: 0 - modifiers: - - type: date - required: true - sort_order: 0 - config: - default_value: string - checked_by_default: true - checkbox_label: string - date_limited: true - date_limit_mode: range - date_earliest_value: '2019-08-24T00:00:00+00:00' - date_latest_value: '2019-08-24T00:00:00+00:00' - file_types_mode: specific - file_types_supported: - - 'images, documents, other' - file_types_other: - - pdf - file_max_size: 5 - text_characters_limited: true - text_min_length: 1 - text_max_length: 55 - text_lines_limited: true - text_max_lines: 4 - number_limited: true - number_limit_mode: lowest - number_lowest_value: 100 - number_highest_value: 0 - number_integers_only: false - product_list_adjusts_inventory: true - product_list_adjusts_pricing: true - product_list_shipping_calc: weight - display_name: string - id: 12 - product_id: 77 - name: Add-a-$5-Donation1535039590-191 - option_values: - - is_default: false - label: Green - sort_order: 0 - value_data: {} - adjusters: - price: - adjuster: relative - adjuster_value: 5 - weight: - adjuster: relative - adjuster_value: 5 - image_url: 'https://cdn8.bigcommerce.com/s-{{store_hash}}/products/184/images/445/naturalcanvascart2_1024x1024__92347__29648.1534344533.1280.1280.jpg?c=2' - purchasing_disabled: - status: true - message: string - id: 0 - option_id: 0 - option_set_id: 0 - option_set_display: string - variants: - - cost_price: 0 - price: 0 - sale_price: 0 - retail_price: 0 - weight: 0 - width: 0 - height: 0 - depth: 0 - is_free_shipping: true - fixed_cost_shipping_price: 0 - purchasing_disabled: true - purchasing_disabled_message: string - upc: string - inventory_level: 0 - inventory_warning_level: 0 - bin_picking_number: string - mpn: string - gtin: '012345678905' - id: 0 - product_id: 0 - sku: string - sku_id: 0 - option_values: - - option_display_name: Color - label: Beige - id: 146 - option_id: 151 - calculated_price: 0 - calculated_weight: 0 - meta: {} - ProductReviewCollectionResponse: - description: '' - content: - application/json: - schema: - title: Product Review Collection Response - type: object - properties: - data: - type: array - items: - title: Product Review - type: object - description: | - A product review model. - allOf: - - title: Product Review Base - required: - - date_reviewed - - title - type: object - properties: - title: - maxLength: 255 - minLength: 0 - type: string - description: |- - The title for the product review. - Required in /POST. - text: - type: string - description: | - The text for the product review. - status: - type: string - description: | - The status of the product review. Must be one of `approved`, `disapproved` or `pending`. - rating: - type: integer - description: 'The rating of the product review. Must be one of 0, 1, 2, 3, 4, 5.' - email: - type: string - description: 'The email of the reviewer. Must be a valid email, or an empty string.' - name: - maxLength: 255 - minLength: 0 - type: string - description: The name of the reviewer. - date_reviewed: - type: string - description: | - Date the product was reviewed. Required in /POST. - format: date-time - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the product review; increments sequentially. - product_id: - type: integer - description: | - The unique numeric identifier for the product with which the review is associated. - date_created: - type: string - description: | - Date the product review was created. - format: date-time - date_modified: - type: string - description: | - Date the product review was modified. - format: date-time - meta: - $ref: '#/components/schemas/metaCollection_Full' - ProductReviewResponse: - description: '' - content: - application/json: - schema: - title: Product Review Response - type: object - properties: - data: - title: Product Review - type: object - description: | - A product review model. - allOf: - - title: Product Review Base - required: - - date_reviewed - - title - type: object - properties: - title: - maxLength: 255 - minLength: 0 - type: string - description: |- - The title for the product review. - Required in /POST. - text: - type: string - description: | - The text for the product review. - status: - type: string - description: | - The status of the product review. Must be one of `approved`, `disapproved` or `pending`. - rating: - type: integer - description: 'The rating of the product review. Must be one of 0, 1, 2, 3, 4, 5.' - email: - type: string - description: 'The email of the reviewer. Must be a valid email, or an empty string.' - name: - maxLength: 255 - minLength: 0 - type: string - description: The name of the reviewer. - date_reviewed: - type: string - description: | - Date the product was reviewed. Required in /POST. - format: date-time - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the product review; increments sequentially. - product_id: - type: integer - description: | - The unique numeric identifier for the product with which the review is associated. - date_created: - type: string - description: | - Date the product review was created. - format: date-time - date_modified: - type: string - description: | - Date the product review was modified. - format: date-time - meta: - title: Meta - type: object - properties: {} - description: Empty meta object; may be used later. - description: | - Response payload for the BigCommerce API. - example: - data: - title: irur - text: anim aute - status: Lorem ad sed voluptate - rating: -39218623 - email: esse Lorem laborum aute - name: 'ut in ' - date_reviewed: '2011-12-31T13:40:42.971Z' - id: 82495037 - product_id: 22609026 - date_created: '1985-01-17T07:37:20.439Z' - date_modified: '2004-09-28T14:38:21.973Z' - meta: {} - ProductSortOrderResponse: - description: '' - content: - application/json: - schema: - type: object - ProductVideoCollectionResponse: - description: '' - content: - application/json: - schema: - title: Product Video Collection Response - type: object - properties: - data: - type: array - items: - title: Product Video - type: object - description: | - A product video model. - allOf: - - title: Product Video Base - type: object - properties: - title: - maxLength: 255 - minLength: 0 - type: string - description: | - The title for the video. If left blank, this will be filled in according to data on a host site. - description: - type: string - description: | - The description for the video. If left blank, this will be filled in according to data on a host site. - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the video will be displayed on the product page. Higher integers give the video a lower priority. When updating, if the video is given a lower priority, all videos with a `sort_order` the same as or greater than the video's new `sort_order` value will have their `sort_order`s reordered. - type: - type: string - description: | - The video type (a short name of a host site). - enum: - - youtube - description: Common Product Video properties. - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the product video; increments sequentially. - video_id: - type: string - description: | - The ID of the video on a host site. - product_id: - type: integer - description: | - The unique numeric identifier for the product with which the image is associated. - length: - type: string - description: | - Length of the video. This will be filled in according to data on a host site. - meta: - title: Collection Meta - type: object - description: 'Data about the response, including pagination and collection totals.' - example: - data: - - id: 6 - type: youtube - video_id: PqBTp23RLhI - product_id: 192 - sort_order: 1 - title: Creating and Editing Banners | BigCommerce Tutorials - description: 'Learn how to create and edit marketing banners. Marketing banners are a great way to advertise sales, display coupon codes, and add design elements. Let’s take a look at how you can leverage banners to convert your store’s visitors into paying customers.' - length: '01:54' - - id: 7 - type: youtube - video_id: EhYBjzqd-nI - product_id: 192 - sort_order: 2 - title: BigCommerce Company Values - description: |- - These are the core principles upon which BigCommerce was built, guiding what we do and how we do it. Each employee learns them, loves them and lives them. Our merchants benefit from them every time they use our product or get help from our support team. - - Join the BigCommerce team and help us build software that changes lives! - - https://www.bigcommerce.com/careers/ - length: '03:30' - - id: 8 - type: youtube - video_id: vAUdo4kRjrU - product_id: 192 - sort_order: 3 - title: TOP WORKPLACES 2016 - Austin American Statesman + BigCommerce - description: |- - We've been named one of Austin American-Statesman's Top WorkPlaces for the 5th year in a row! Here's what some employees have to say: - - “I am given the freedom and trust to make a difference.” - - “Everyone believes in the product and growing the company.” - - “I'm appreciated for the work I do and there is room to grown within the company.” - - Work With Us! - http://www.bigcommerce.com/careers.php - length: '01:37' - meta: - pagination: - total: 3 - count: 3 - per_page: 50 - current_page: 1 - total_pages: 1 - links: - current: '?page=1&limit=50' - ProductVideoResponse: - description: '' - content: - application/json: - schema: - title: Product Video Response - type: object - properties: - data: - title: Product Video - type: object - description: | - A product video model. - allOf: - - title: Product Video Base - type: object - properties: - title: - maxLength: 255 - minLength: 0 - type: string - description: | - The title for the video. If left blank, this will be filled in according to data on a host site. - description: - type: string - description: | - The description for the video. If left blank, this will be filled in according to data on a host site. - sort_order: - maximum: 2147483647 - minimum: -2147483648 - type: integer - description: | - The order in which the video will be displayed on the product page. Higher integers give the video a lower priority. When updating, if the video is given a lower priority, all videos with a `sort_order` the same as or greater than the video's new `sort_order` value will have their `sort_order`s reordered. - type: - type: string - description: | - The video type (a short name of a host site). - enum: - - youtube - description: Common Product Video properties. - - type: object - properties: - id: - type: integer - description: | - The unique numeric ID of the product video; increments sequentially. - video_id: - type: string - description: | - The ID of the video on a host site. - product_id: - type: integer - description: | - The unique numeric identifier for the product with which the image is associated. - length: - type: string - description: | - Length of the video. This will be filled in according to data on a host site. - meta: - $ref: '#/components/schemas/metaEmpty_Full' - description: | - Response payload for the BigCommerce API. - example: - title: Your Video - description: Company Values - sort_order: 1 - type: youtube - video_id: 123345AA - VariantCollectionResponse: - description: '' - content: - application/json: - schema: - title: Variant Collection Response - type: object - properties: - data: - type: array - items: - type: object - allOf: - - title: Variant Base - type: object - properties: - cost_price: - minimum: 0 - type: number - description: The cost price of the variant. Not affected by Price List prices. - format: double - x-nullable: true - price: - minimum: 0 - type: number - description: 'This variant’s base price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is `null`, the product’s default price (set in the Product resource’s `price` field) will be used as the base price.' - format: double - x-nullable: true - sale_price: - minimum: 0 - type: number - description: 'This variant’s sale price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s sale price (set in the Product resource’s `price` field) will be used as the sale price.' - format: double - x-nullable: true - retail_price: - minimum: 0 - type: number - description: 'This variant’s retail price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s retail price (set in the Product resource’s `price` field) will be used as the retail price.' - format: double - x-nullable: true - weight: - minimum: 0 - type: number - description: 'This variant’s base weight on the storefront. If this value is null, the product’s default weight (set in the Product resource’s weight field) will be used as the base weight.' - format: double - x-nullable: true - width: - minimum: 0 - type: number - description: | - Width of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default width (set in the Product resource's `width` field) will be used as the base width. - format: double - x-nullable: true - height: - minimum: 0 - type: number - description: | - Height of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default height (set in the Product resource's `height` field) will be used as the base height. - format: double - x-nullable: true - depth: - minimum: 0 - type: number - description: | - Depth of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default depth (set in the Product resource's `depth` field) will be used as the base depth. - format: double - x-nullable: true - is_free_shipping: - type: boolean - description: | - Flag used to indicate whether the variant has free shipping. If `true`, the shipping cost for the variant will be zero. - fixed_cost_shipping_price: - minimum: 0 - type: number - description: | - A fixed shipping cost for the variant. If defined, this value will be used during checkout instead of normal shipping-cost calculation. - format: double - x-nullable: true - purchasing_disabled: - type: boolean - description: 'If `true`, this variant will not be purchasable on the storefront.' - purchasing_disabled_message: - maxLength: 255 - minLength: 0 - type: string - description: 'If `purchasing_disabled` is `true`, this message should show on the storefront when the variant is selected.' - upc: - type: string - description: The UPC code used in feeds for shopping comparison sites and external channel integrations. - x-nullable: true - inventory_level: - type: integer - description: 'Inventory level for the variant, which is used when the product’s inventory_tracking is set to `variant`.' - x-nullable: true - inventory_warning_level: - type: integer - description: 'When the variant hits this inventory level, it is considered low stock.' - x-nullable: true - bin_picking_number: - maxLength: 255 - minLength: 0 - type: string - description: Identifies where in a warehouse the variant is located. - x-nullable: true - description: Common Variant properties. - - type: object - properties: - id: - type: integer - product_id: - type: integer - sku: - type: string - sku_id: - type: integer - description: Read-only reference to v2 API's SKU ID. Null if it is a base variant. - x-nullable: true - option_values: - type: array - description: Array of option and option values IDs that make up this variant. Will be empty if the variant is the product's base variant. - items: - title: Option Value Variant - type: object - allOf: - - title: Option Value Product Base - type: object - properties: - option_display_name: - maxLength: 255 - minLength: 1 - type: string - description: | - The name of the option. - example: Color - x-required: - - post - label: - maxLength: 255 - minLength: 1 - type: string - description: | - The label of the option value. - example: Beige - x-required: - - post - description: Common Option Value Product properties. - - type: object - properties: - id: - type: integer - option_id: - type: integer - calculated_price: - type: number - description: | - The price of the variant as seen on the storefront. This price takes into account `sale_price` and any price adjustment rules that are applicable to this variant. - format: double - meta: - title: Collection Meta - type: object - description: 'Data about the response, including pagination and collection totals.' - VariantResponse: - description: '' - content: - application/json: - schema: - title: Variant Response - type: object - properties: - data: - type: object - allOf: - - title: Variant Base - type: object - properties: - cost_price: - minimum: 0 - type: number - description: The cost price of the variant. Not affected by Price List prices. - format: double - x-nullable: true - price: - minimum: 0 - type: number - description: 'This variant’s base price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is `null`, the product’s default price (set in the Product resource’s `price` field) will be used as the base price.' - format: double - x-nullable: true - sale_price: - minimum: 0 - type: number - description: 'This variant’s sale price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s sale price (set in the Product resource’s `price` field) will be used as the sale price.' - format: double - x-nullable: true - retail_price: - minimum: 0 - type: number - description: 'This variant’s retail price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s retail price (set in the Product resource’s `price` field) will be used as the retail price.' - format: double - x-nullable: true - weight: - minimum: 0 - type: number - description: 'This variant’s base weight on the storefront. If this value is null, the product’s default weight (set in the Product resource’s weight field) will be used as the base weight.' - format: double - x-nullable: true - width: - minimum: 0 - type: number - description: | - Width of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default width (set in the Product resource's `width` field) will be used as the base width. - format: double - x-nullable: true - height: - minimum: 0 - type: number - description: | - Height of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default height (set in the Product resource's `height` field) will be used as the base height. - format: double - x-nullable: true - depth: - minimum: 0 - type: number - description: | - Depth of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default depth (set in the Product resource's `depth` field) will be used as the base depth. - format: double - x-nullable: true - is_free_shipping: - type: boolean - description: | - Flag used to indicate whether the variant has free shipping. If `true`, the shipping cost for the variant will be zero. - fixed_cost_shipping_price: - minimum: 0 - type: number - description: | - A fixed shipping cost for the variant. If defined, this value will be used during checkout instead of normal shipping-cost calculation. - format: double - x-nullable: true - purchasing_disabled: - type: boolean - description: 'If `true`, this variant will not be purchasable on the storefront.' - purchasing_disabled_message: - maxLength: 255 - minLength: 0 - type: string - description: 'If `purchasing_disabled` is `true`, this message should show on the storefront when the variant is selected.' - upc: - type: string - description: The UPC code used in feeds for shopping comparison sites and external channel integrations. - x-nullable: true - inventory_level: - type: integer - description: 'Inventory level for the variant, which is used when the product’s inventory_tracking is set to `variant`.' - x-nullable: true - inventory_warning_level: - type: integer - description: 'When the variant hits this inventory level, it is considered low stock.' - x-nullable: true - bin_picking_number: - maxLength: 255 - minLength: 0 - type: string - description: Identifies where in a warehouse the variant is located. - x-nullable: true - description: Common Variant properties. - - type: object - properties: - id: - type: integer - product_id: - type: integer - sku: - type: string - sku_id: - type: integer - description: Read-only reference to v2 API's SKU ID. Null if it is a base variant. - x-nullable: true - option_values: - type: array - description: Array of option and option values IDs that make up this variant. Will be empty if the variant is the product's base variant. - items: - title: Option Value Variant - type: object - allOf: - - title: Option Value Product Base - type: object - properties: - option_display_name: - maxLength: 255 - minLength: 1 - type: string - description: | - The name of the option. - example: Color - x-required: - - post - label: - maxLength: 255 - minLength: 1 - type: string - description: | - The label of the option value. - example: Beige - x-required: - - post - description: Common Option Value Product properties. - - type: object - properties: - id: - type: integer - option_id: - type: integer - calculated_price: - type: number - description: | - The price of the variant as seen on the storefront. This price takes into account `sale_price` and any price adjustment rules that are applicable to this variant. - format: double - meta: - title: Meta - type: object - properties: {} - description: Empty meta object; may be used later. - betaCategoryCollectionResponse: - description: '' - content: - application/json: - schema: - type: object - title: Category Base - properties: - data: - type: array - items: {} - meta: - $ref: '#/components/schemas/betametaCollection_Full' - examples: - response: - value: - data: - - id: 19 - parent_id: 0 - name: Garden - description: This is the garden description - views: 0 - sort_order: 2 - page_title: page title - meta_keywords: - - meta keyword - meta_description: meta description - layout_file: category.html - image_url: '' - is_visible: true - search_keywords: search keywords - default_product_sort: use_store_settings - custom_url: - url: /garden/ - is_customized: false - - id: 20 - parent_id: 0 - name: Publications - description: '' - views: 0 - sort_order: 4 - page_title: '' - meta_keywords: - - '' - meta_description: '' - layout_file: category_with_facets.html - image_url: '' - is_visible: true - search_keywords: '' - default_product_sort: use_store_settings - custom_url: - url: /publications/ - is_customized: false - - id: 21 - parent_id: 0 - name: Kitchen - description: '' - views: 0 - sort_order: 3 - page_title: '' - meta_keywords: - - '' - meta_description: '' - layout_file: category_with_facets.html - image_url: '' - is_visible: true - search_keywords: '' - default_product_sort: use_store_settings - custom_url: - url: /kitchen/ - is_customized: false - - id: 22 - parent_id: 0 - name: Utility - description: '' - views: 0 - sort_order: 5 - page_title: '' - meta_keywords: - - '' - meta_description: '' - layout_file: category_with_facets.html - image_url: '' - is_visible: true - search_keywords: '' - default_product_sort: use_store_settings - custom_url: - url: /utility/ - is_customized: false - - id: 23 - parent_id: 0 - name: Shop All - description: '' - views: 0 - sort_order: 0 - page_title: '' - meta_keywords: - - '' - meta_description: '' - layout_file: category_with_facets.html - image_url: '' - is_visible: true - search_keywords: '' - default_product_sort: use_store_settings - custom_url: - url: /shop-all/ - is_customized: false - - id: 39 - parent_id: 19 - name: Bath - description: '' - views: 0 - sort_order: 0 - page_title: '' - meta_keywords: - - '' - meta_description: '' - layout_file: category.html - image_url: '' - is_visible: true - search_keywords: '' - default_product_sort: use_store_settings - custom_url: - url: /garden/bath/ - is_customized: false - meta: - pagination: - total: 6 - count: 6 - per_page: 50 - current_page: 1 - total_pages: 1 - links: - current: '?page=1&limit=50' - betaCategoryResponse: - description: '' - content: - application/json: - schema: - type: object - title: Category Response - properties: - data: - $ref: '#/components/schemas/betacategory_Full' - meta: - $ref: '#/components/schemas/metaEmpty_Full' - parameters: - FilterTemplateFileParam: - name: template_file - in: query - description: 'The template file, for example: `pages/home`.' - schema: - type: string - FilterIdParam: - name: id - in: query - description: | - Filter items by id. - schema: - type: integer - FilterSkuParam: - name: sku - in: query - description: | - Filter items by sku. - schema: - type: string - FilterNameParam: - name: name - in: query - description: | - Filter items by name. - schema: - type: string - FilterEmailParam: - name: email - in: query - description: | - Filter items by email. - schema: - type: string - FilterSourceParam: - name: source - in: query - description: | - Filter items by source. - schema: - type: string - FilterOrderIdParam: - name: order_id - in: query - description: | - Filter items by order_id. - schema: - type: integer - FilterUpcParam: - name: upc - in: query - description: | - Filter items by upc. - schema: - type: string - FilterPriceParam: - name: price - in: query - description: | - Filter items by price. - schema: - type: number - FilterSalePriceParam: - name: sale_price - in: query - description: | - Filter items by sale_price. - schema: - type: number - FilterRetailPriceParam: - name: retail_price - in: query - description: | - Filter items by retail_price. - schema: - type: number - FilterMapPriceParam: - name: map_price - in: query - description: | - Filter items by map_price. - schema: - type: number - FilterCalculatedPriceParam: - name: calculated_price - in: query - description: | - Filter items by calculated_price. - schema: - type: number - FilterWeightParam: - name: weight - in: query - description: | - Filter items by weight. - schema: - type: number - FilterConditionParam: - name: condition - in: query - description: | - Filter items by condition. - schema: - type: string - enum: - - new - - used - - refurbished - FilterBrandIdParam: - name: brand_id - in: query - description: | - Filter items by brand_id. - schema: - type: integer - FilterDateModifiedParam: - name: date_modified - in: query - description: 'Filter items by date_modified. For example `v3/catalog/products?date_modified:min=2018-06-15`' - schema: - type: string - format: date-time - FilterDateCreatedParam: - name: date_created - in: query - description: | - Filter items by date_created. - schema: - type: string - format: date-time - FilterDateLastImportedParam: - name: date_last_imported - in: query - description: 'Filter items by date_last_imported. For example `v3/catalog/products?date_last_imported:min=2018-06-15`' - schema: - type: string - format: date-time - FilterIsVisibleParam: - name: is_visible - in: query - description: 'Filter items by if visible on the storefront. ' - schema: - type: boolean - FilterIsFeaturedParam: - name: is_featured - in: query - description: | - Filter items by is_featured. - schema: - type: integer - FilterIsFreeShippingParam: - name: is_free_shipping - in: query - description: | - Filter items by is_free_shipping. - schema: - type: integer - FilterInventoryLevelParam: - name: inventory_level - in: query - description: | - Filter items by inventory_level. - schema: - type: integer - FilterInventoryLowParam: - name: inventory_low - in: query - description: | - Filter items by inventory_low. Values: 1, 0. - schema: - type: integer - FilterOutOfStockParam: - name: out_of_stock - in: query - description: | - Filter items by out_of_stock. To enable the filter, pass `out_of_stock`=`1`. - schema: - type: integer - FilterTotalSoldParam: - name: total_sold - in: query - description: | - Filter items by total_sold. - schema: - type: integer - ProductFilterTypeParam: - name: type - in: query - description: 'Filter items by type: `physical` or `digital`.' - schema: - type: string - enum: - - digital - - physical - FilterCategoriesParam: - name: categories - in: query - description: |- - Filter items by categories. - If a product is in more than one category, using this query will not return the product. Instead use `categories:in=12`. - schema: - type: integer - FilterKeywordParam: - name: keyword - in: query - description: 'Filter items by keywords. eg. new, towel, bath' - schema: - type: string - ProductFilterKeywordParam: - name: keyword - in: query - description: | - Filter items by keywords found in the `name`, `description`, or `sku` fields, or in the brand name. - schema: - type: string - ProductFilterKeywordContextParam: - name: keyword_context - in: query - description: Set context for a product search. - schema: - type: string - enum: - - shopper - - merchant - FilterStatusParam: - name: status - in: query - description: | - Filter items by status. - schema: - type: integer - FilterIncludeParam: - name: include - in: query - description: 'Sub-resources to include on a product, in a comma-separated list. If `options` or `modifiers` is used, results are limited to 10 per page.' - schema: - type: string - enum: - - variants - - images - - custom_fields - - bulk_pricing_rules - - primary_image - - modifiers - - options - - videos - FilterIncludeFieldsParam: - name: include_fields - in: query - description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' - schema: - type: string - FilterExcludeFieldsParam: - name: exclude_fields - in: query - description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' - schema: - type: string - FilterParentIdParam: - name: parent_id - in: query - description: 'Filter items by parent_id. If the category is a child or sub category it can be filtered with the parent_id. ' - schema: - type: integer - FilterPageTitleParam: - name: page_title - in: query - description: | - Filter items by page_title. - schema: - type: string - FilterAvailabilityParam: - name: availability - in: query - description: | - Filter items by availability. Values are: available, disabled, preorder. - schema: - type: string - enum: - - available - - disabled - - preorder - FilterProductIdParam: - name: product_id - in: query - description: | - A comma-separated list of ids of `Product`s whose prices were requested. - schema: - type: string - FilterVariantIdParam: - name: variant_id - in: query - description: | - The ID of the `Variant` whose prices were requested. - schema: - type: integer - FilterCurrencyParam: - name: currency - in: query - description: | - Filter items by currency. - schema: - type: string - format: ISO-4217 - PageParam: - name: page - in: query - description: Specifies the page number in a limited (paginated) list of products. - schema: - type: integer - LimitParam: - name: limit - in: query - description: Controls the number of items per page in a limited (paginated) list of products. - schema: - type: integer - DirectionParam: - name: direction - in: query - description: | - Sort direction. Acceptable values are: `asc`, `desc`. - schema: - type: string - enum: - - asc - - desc - ProductSortParam: - name: sort - in: query - description: | - Field name to sort by. - schema: - type: string - enum: - - id - - name - - sku - - price - - date_modified - - date_last_imported - - inventory_level - - is_visible - - total_sold - ProductIdParam: - name: product_id - in: path - description: | - The ID of the `Product` to which the resource belongs. - required: true - schema: - type: integer - ReviewIdParam: - name: review_id - description: | - The ID of the `review` that is being operated on. - required: true - in: path - schema: - type: integer - ImageIdParam: - name: image_id - description: | - The ID of the `Image` that is being operated on. - required: true - in: path - schema: - type: integer - VideoIdParam: - name: id - description: The BigCommerce ID of the `Video` - required: true - in: path - schema: - type: integer - ComplexRuleIdParam: - name: complex_rule_id - description: | - The ID of the `ComplexRule`. - required: true - in: path - schema: - type: integer - ConfigurableFieldIdParam: - name: configurable_field_id - description: | - The ID of the `ConfigurableField`. - required: true - in: path - schema: - type: integer - CustomFieldIdParam: - name: custom_field_id - description: | - The ID of the `CustomField`. - required: true - in: path - schema: - type: integer - BulkPricingRuleIdParam: - name: bulk_pricing_rule_id - description: | - The ID of the `BulkPricingRule`. - required: true - in: path - schema: - type: integer - ModifierIdParam: - name: modifier_id - description: | - The ID of the `Modifier`. - required: true - in: path - schema: - type: integer - ValueIdParam: - name: value_id - description: | - The ID of the `Modifier/Option Value`. - required: true - in: path - schema: - type: integer - OptionIdParam: - name: option_id - description: | - The ID of the `Option`. - required: true - in: path - schema: - type: integer - VariantIdParam: - name: variant_id - in: path - description: | - ID of the variant on a product, or on an associated Price List Record. - required: true - schema: - type: integer - CategoryIdParam: - name: category_id - in: path - description: | - The ID of the `Category` to which the resource belongs. - required: true - schema: - type: integer - BrandIdParam: - name: brand_id - in: path - description: | - The ID of the `Brand` to which the resource belongs. - required: true - schema: - type: integer - MetafieldIdParam: - name: metafield_id - in: path - description: | - The ID of the `Metafield`. - required: true - schema: - type: integer - MetafieldKeyParam: - name: key - in: query - description: | - Filter based on a metafield's key. - schema: - type: string - MetafieldNamespaceParam: - name: namespace - in: query - description: Filter based on a metafield's namespace. - schema: - type: string - OrderIdParam: - name: order_id - in: path - description: | - The ID of the `Order` to which the transactions belong. - required: true - schema: - type: integer - Accept: - name: Accept - in: header - required: true - description: 'The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body.' - schema: - type: string - default: 'application/json' - ContentType: - name: Content-Type - in: header - required: true - description: 'The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the request body.' - schema: - type: string - default: 'application/json' - product_id: - name: product_id - in: query - description: |- - A comma-separated list of ids of Products whose prices were requested. For example: - `?product_id=:id` - `?product_id:in=77,80,81` - schema: - type: string - FilterIdIn: - name: 'id:in' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - FilterIdNotIn: - name: 'id:not_in' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - FilterIdMax: - name: 'id:max' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - FilterIdMin: - name: 'id:min' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - FilterIdGreater: - name: 'id:greater' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - FilterIdLess: - name: 'id:less' - in: query - style: form - explode: false - schema: - type: array - items: - type: integer - betaFilterTemplateFileParam: - in: query - name: template_file - description: 'The template file, for example: `pages/home`.' - required: false - schema: - type: string - betaFilterIdParam: - name: id - description: | - Filter items by id. - required: false - in: query - schema: - type: integer - betaFilterSkuParam: - name: sku - description: | - Filter items by sku. - required: false - in: query - schema: - type: string - betaFilterNameParam: - name: name - description: | - Filter items by name. - required: false - in: query - schema: - type: string - betaFilterEmailParam: - name: email - description: | - Filter items by email. - required: false - in: query - schema: - type: string - betaFilterSourceParam: - name: source - description: | - Filter items by source. - required: false - in: query - schema: - type: string - betaFilterOrderIdParam: - name: order_id - description: | - Filter items by order_id. - required: false - in: query - schema: - type: integer - betaFilterUpcParam: - name: upc - description: | - Filter items by upc. - required: false - in: query - schema: - type: string - betaFilterPriceParam: - name: price - description: | - Filter items by price. - required: false - in: query - schema: - type: number - betaFilterSalePriceParam: - name: sale_price - description: | - Filter items by sale_price. - required: false - in: query - schema: - type: number - betaFilterRetailPriceParam: - name: retail_price - description: | - Filter items by retail_price. - required: false - in: query - schema: - type: number - betaFilterMapPriceParam: - name: map_price - description: | - Filter items by map_price. - required: false - in: query - schema: - type: number - betaFilterCalculatedPriceParam: - name: calculated_price - description: | - Filter items by calculated_price. - required: false - in: query - schema: - type: number - betaFilterWeightParam: - name: weight - description: | - Filter items by weight. - required: false - in: query - schema: - type: number - betaFilterConditionParam: - name: condition - description: | - Filter items by condition. - required: false - in: query - schema: - type: string - enum: - - new - - used - - refurbished - betaFilterBrandIdParam: - name: brand_id - description: | - Filter items by brand_id. - required: false - in: query - schema: - type: integer - betaFilterDateModifiedParam: - name: date_modified - description: 'Filter items by date_modified. For example `v3/catalog/products?date_modified:min=2018-06-15`' - required: false - in: query - schema: - type: string - format: date-time - betaFilterDateCreatedParam: - name: date_created - description: | - Filter items by date_created. - required: false - in: query - schema: - type: string - format: date-time - betaFilterDateLastImportedParam: - name: date_last_imported - description: 'Filter items by date_last_imported. For example `v3/catalog/products?date_last_imported:min=2018-06-15`' - required: false - in: query - schema: - type: string - format: date-time - betaFilterIsVisibleParam: - name: is_visible - description: 'Filter items by if visible on the storefront. ' - required: false - in: query - schema: - type: boolean - betaFilterIsFeaturedParam: - name: is_featured - description: | - Filter items by is_featured. - required: false - in: query - schema: - type: integer - betaFilterIsFreeShippingParam: - name: is_free_shipping - description: | - Filter items by is_free_shipping. - required: false - in: query - schema: - type: integer - betaFilterInventoryLevelParam: - name: inventory_level - description: | - Filter items by inventory_level. - required: false - in: query - schema: - type: integer - betaFilterInventoryLowParam: - name: inventory_low - description: | - Filter items by inventory_low. Values: 1, 0. - required: false - in: query - schema: - type: integer - betaFilterOutOfStockParam: - name: out_of_stock - description: | - Filter items by out_of_stock. To enable the filter, pass `out_of_stock`=`1`. - required: false - in: query - schema: - type: integer - betaFilterTotalSoldParam: - name: total_sold - description: | - Filter items by total_sold. - required: false - in: query - schema: - type: integer - betaProductFilterTypeParam: - name: type - description: 'Filter items by type: `physical` or `digital`.' - required: false - in: query - schema: - type: string - enum: - - digital - - physical - betaFilterCategoriesParam: - name: categories - description: |- - Filter items by categories. - If a product is in more than one category, using this query will not return the product. Instead use `categories:in=12`. - required: false - in: query - schema: - type: integer - betaFilterKeywordParam: - name: keyword - description: 'Filter items by keywords. eg. new, towel, bath' - required: false - in: query - schema: - type: string - betaProductFilterKeywordParam: - name: keyword - description: | - Filter items by keywords found in the `name`, `description`, or `sku` fields, or in the brand name. - required: false - in: query - schema: - type: string - betaProductFilterKeywordContextParam: - name: keyword_context - description: Set context for a product search. - required: false - in: query - schema: - type: string - enum: - - shopper - - merchant - betaFilterStatusParam: - name: status - description: | - Filter items by status. - required: false - in: query - schema: - type: integer - betaFilterIncludeParam: - name: include - description: 'Sub-resources to include on a product, in a comma-separated list. If `options` or `modifiers` is used, results are limited to 10 per page.' - required: false - in: query - schema: - type: string - enum: - - variants - - images - - custom_fields - - bulk_pricing_rules - - primary_image - - modifiers - - options - - videos - betaFilterIncludeFieldsParam: - name: include_fields - description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' - required: false - in: query - schema: - type: string - betaFilterExcludeFieldsParam: - name: exclude_fields - description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' - required: false - in: query - schema: - type: string - betaFilterParentIdParam: - name: parent_id - description: 'Filter items by parent_id. If the category is a child or sub category it can be filtered with the parent_id. ' - required: false - in: query - schema: - type: integer - betaFilterPageTitleParam: - name: page_title - description: | - Filter items by page_title. - required: false - in: query - schema: - type: string - betaFilterAvailabilityParam: - name: availability - description: | - Filter items by availability. Values are: available, disabled, preorder. - required: false - in: query - schema: - type: string - enum: - - available - - disabled - - preorder - betaFilterProductIdParam: - name: product_id - in: query - required: false - description: | - A comma-separated list of ids of `Product`s whose prices were requested. - schema: - type: string - betaFilterVariantIdParam: - name: variant_id - in: query - required: false - description: | - The ID of the `Variant` whose prices were requested. - schema: - type: integer - betaFilterCurrencyParam: - name: currency - description: | - Filter items by currency. - required: false - in: query - schema: - type: string - format: ISO-4217 - betaPageParam: - name: page - description: Specifies the page number in a limited (paginated) list of products. - required: false - in: query - schema: - type: integer - betaLimitParam: - name: limit - description: Controls the number of items per page in a limited (paginated) list of products. - required: false - in: query - schema: - type: integer - betaDirectionParam: - name: direction - description: | - Sort direction. Acceptable values are: `asc`, `desc`. - required: false - in: query - schema: - type: string - enum: - - asc - - desc - betaProductSortParam: - name: sort - description: | - Field name to sort by. - required: false - in: query - schema: - type: string - enum: - - id - - name - - sku - - price - - date_modified - - date_last_imported - - inventory_level - - is_visible - - total_sold - betaFilterIdIn: - in: query - name: 'id:in' - schema: - type: array - items: - type: integer - betaFilterIdNotIn: - in: query - name: 'id:not_in' - schema: - type: array - items: - type: integer - betaFilterIdMax: - in: query - name: 'id:max' - schema: - type: array - items: - type: integer - betaFilterIdMin: - in: query - name: 'id:min' - schema: - type: array - items: - type: integer - betaFilterIdGreater: - in: query - name: 'id:greater' - schema: - type: array - items: - type: integer - betaFilterIdLess: - in: query - name: 'id:less' - schema: - type: array - items: - type: integer - securitySchemes: - X-Auth-Token: - name: X-Auth-Token - description: |- - ### OAuth scopes - - | UI Name | Permission | Parameter | - |:--------|:-----------|:----------| - | Products | modify | `store_v2_products` | - | Products | read-only | `store_v2_products_read_only` | - - ### Authentication header - - | Header | Argument | Description | - |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | - - ### Further reading - - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). - - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). - - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). - type: apiKey - in: header - diff --git a/reference/catalog/brands_catalog.v3.yml b/reference/catalog/brands_catalog.v3.yml new file mode 100644 index 000000000..6cdf70696 --- /dev/null +++ b/reference/catalog/brands_catalog.v3.yml @@ -0,0 +1,1917 @@ +openapi: '3.0.3' +info: + title: Catalog - Brands + description: |- + > The Catalog API manages products, categories, brands, bulk pricing rules, and more. To learn more about catalog resources, see the [Catalog Overview](/docs/store-operations/catalog). + + Our Catalog Brands endpoints let you [create individual brands](/docs/rest-catalog/brands#create-a-brand) and [modify the brands](/docs/rest-catalog/brands#update-a-brand) associated with a store's products, along with [deleting brands](/docs/rest-catalog/brands#delete-a-brand). + + Brand images have their own dedicated [create a brand image](/docs/rest-catalog/brands/images#create-a-brand-image) and [delete a brand image](/docs/rest-catalog/brands/images#delete-a-brand-image) endpoints. + + In addition, brands have metafields that you can use to store information structured in key-value pairs; learn more about [creating brand metafields](/docs/rest-catalog/brands/metafields#create-a-brand-metafield), [updating brand metafields](/docs/rest-catalog/brands/metafields#update-a-brand-metafield), and [deleting brand metafields](/docs/rest-catalog/brands/metafields#delete-a-brand-metafield). + + > To learn more about authenticating Catalog endpoints, locate the **Authentication** section at the top of each endpoint, then click **Show Details**. + + ## Resources + + ### Webhooks + * [Category](/docs/integrations/webhooks/events#category) + + ### Additional Catalog endpoints + * [Categories](/docs/rest-catalog/categories) + * [Category Trees](/docs/rest-catalog/category-trees) + * [Products](/docs/rest-catalog/products) + * [Product Modifiers](/docs/rest-catalog/product-modifiers) + * [Product Variants](/docs/rest-catalog/product-variants) + * [Product Variant Options](/docs/rest-catalog/product-variant-options) + + termsOfService: 'https://www.bigcommerce.com/terms' + contact: + name: BigCommerce + url: 'https://www.bigcommerce.com' + email: support@bigcommerce.com + version: '' +servers: + - url: 'https://api.bigcommerce.com/stores/{store_hash}/v3' + variables: + store_hash: + default: store_hash + description: Permanent ID of the BigCommerce store. + description: BigCommerce API Gateway +security: + - X-Auth-Token: [] +tags: + - name: Brands + - name: Images + - name: Metafields +paths: + '/catalog/brands': + get: + tags: + - Brands + summary: Get All Brands + description: Returns a list of *Brands*. Optional filter parameters can be passed in. + operationId: getBrands + parameters: + - name: id + in: query + description: | + Filter items by ID. + schema: + type: integer + - name: 'id:in' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: 'id:not_in' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: 'id:min' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: 'id:max' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: 'id:greater' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: 'id:less' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: name + in: query + description: | + Filter items by name. + schema: + type: string + - name: name:like + in: query + description: |- + Filter items by part of a name. For example, `name:like=new` returns brands with names that include `new`. + schema: + type: string + - name: page_title + in: query + description: | + Filter items by page_title. + schema: + type: string + - name: page + in: query + description: Specifies the page number in a limited (paginated) list of products. + schema: + type: integer + - name: limit + in: query + description: Controls the number of items per page in a limited (paginated) list of products. + schema: + type: integer + - name: include_fields + in: query + description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' + schema: + type: string + - name: exclude_fields + in: query + description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' + schema: + type: string + - name: sort + in: query + description: 'Field name to sort by.' + schema: + type: string + enum: + - name + responses: + '200': + description: '' + content: + application/json: + schema: + title: Brand Collection Response + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/brand_Full' + meta: + $ref: '#/components/schemas/metaCollection_Full' + example: + data: + - id: 35 + name: Sagaform + page_title: '' + meta_keywords: + - '' + meta_description: '' + image_url: '' + search_keywords: '' + custom_url: + url: /brands/Sagaform.html + is_customized: false + - id: 36 + name: OFS + page_title: OFS + meta_keywords: + - modern + - ' clean' + - ' contemporary' + meta_description: OFS is a modern brand. + image_url: '' + search_keywords: 'kitchen, laundry, cart, storage' + custom_url: + url: /brands/OFS.html + is_customized: false + - id: 37 + name: Common Good + page_title: '' + meta_keywords: + - '' + meta_description: '' + image_url: 'https://cdn8.bigcommerce.com/s-jrah6gmn/product_images/k/screen%20shot%202018-05-07%20at%2012.24.24%20pm_1525785365__65102.png' + search_keywords: '' + custom_url: + url: /brands/Common-Good.html + is_customized: false + - id: 38 + name: BigCommerce + page_title: '' + meta_keywords: + - '' + meta_description: '' + image_url: '' + search_keywords: '' + custom_url: + url: /bigcommerce/ + is_customized: false + - id: 39 + name: Test Brand One + page_title: '' + meta_keywords: + - '' + meta_description: '' + image_url: 'https://cdn8.bigcommerce.com/s-jrah6gmn/product_images/q/apihqggzm__53766.jpg' + search_keywords: '' + custom_url: + url: /test-brand-one/ + is_customized: false + - id: 40 + name: Fog Linen Work + page_title: '' + meta_keywords: + - '' + meta_description: description + image_url: '' + search_keywords: '' + custom_url: + url: /fog-linen-work/ + is_customized: false + - id: 41 + name: Barr-Co. + page_title: '' + meta_keywords: + - '' + meta_description: description + image_url: '' + search_keywords: '' + custom_url: + url: /barr-co/ + is_customized: false + - id: 42 + name: Thames & Hudson + page_title: '' + meta_keywords: + - '' + meta_description: description + image_url: '' + search_keywords: '' + custom_url: + url: /thames-hudson/ + is_customized: false + - id: 43 + name: Able Brewing + page_title: '' + meta_keywords: + - '' + meta_description: description + image_url: '' + search_keywords: '' + custom_url: + url: /able-brewing/ + is_customized: false + - id: 44 + name: Chemex + page_title: '' + meta_keywords: + - '' + meta_description: description + image_url: '' + search_keywords: '' + custom_url: + url: /chemex/ + is_customized: false + - id: 45 + name: Kinfolk + page_title: '' + meta_keywords: + - '' + meta_description: description + image_url: '' + search_keywords: '' + custom_url: + url: /kinfolk/ + is_customized: false + - id: 46 + name: Iris Hantverk + page_title: '' + meta_keywords: + - '' + meta_description: description + image_url: '' + search_keywords: '' + custom_url: + url: /iris-hantverk/ + is_customized: false + - id: 47 + name: Gather Journal + page_title: '' + meta_keywords: + - '' + meta_description: description + image_url: '' + search_keywords: '' + custom_url: + url: /gather-journal/ + is_customized: false + - id: 48 + name: Openhouse Magazine + page_title: '' + meta_keywords: + - '' + meta_description: description + image_url: '' + search_keywords: '' + custom_url: + url: /openhouse-magazine/ + is_customized: false + - id: 49 + name: Smith Journal + page_title: '' + meta_keywords: + - '' + meta_description: description + image_url: '' + search_keywords: '' + custom_url: + url: /smith-journal/ + is_customized: false + meta: + pagination: + total: 15 + count: 15 + per_page: 50 + current_page: 1 + total_pages: 1 + links: + current: '?page=1&limit=50' + post: + tags: + - Brands + summary: Create a Brand + description: |- + Creates a *Brand*. + + **Required Fields** + - name + + **Read-Only Fields** + - id + + **Limits** + - 30,000 brands per store limit + operationId: createBrand + parameters: + - $ref: '#/components/parameters/ContentType' + requestBody: + content: + application/json: + schema: + title: Brand + type: object + description: Common brand properties. + properties: + name: + maxLength: 255 + minLength: 1 + type: string + description: |- + The name of the brand. Must be unique. + Required in POST. + example: Common Good + x-required: + - post + - put + page_title: + maxLength: 255 + minLength: 0 + type: string + description: | + The title shown in the browser while viewing the brand. + example: Common Good + meta_keywords: + type: array + description: | + Comma-separated list of meta keywords to include in the HTML. + items: + type: string + example: 'modern, clean, contemporary' + meta_description: + maxLength: 65535 + minLength: 0 + type: string + description: | + A meta description to include. + example: Common Good is a modern brand. + search_keywords: + maxLength: 65535 + minLength: 0 + type: string + description: | + A comma-separated list of keywords that can be used to locate this brand. + example: 'kitchen, laundry, cart, storage' + image_url: + type: string + description: | + Image URL used for this category on the storefront. Images can be uploaded via form file post to `/brands/{brandId}/image`, or by providing a publicly accessible URL in this field. + example: 'https://cdn8.bigcommerce.com/s-12345/product_images/k/your-image-name.png' + x-url: true + custom_url: + title: Custom Url Brand + type: object + description: The custom URL for the brand on the storefront. + properties: + url: + type: string + description: | + Brand URL on the storefront. + example: /shoes + x-url: true + is_customized: + type: boolean + description: | + Returns `true` if the URL has been changed from its default state (the auto-assigned URL that BigCommerce provides). + example: true + required: + - name + required: true + responses: + '200': + description: '' + content: + application/json: + schema: + title: Brand Response + type: object + properties: + data: + title: Brand + type: object + properties: + id: + type: integer + description: Unique ID of the *Brand*. Read-Only. + readOnly: true + name: + maxLength: 255 + minLength: 1 + type: string + description: |- + The name of the brand. Must be unique. + Required in POST. + example: Common Good + x-required: + - post + - put + page_title: + maxLength: 255 + minLength: 0 + type: string + description: | + The title shown in the browser while viewing the brand. + example: Common Good + meta_keywords: + type: array + description: | + Comma-separated list of meta keywords to include in the HTML. + items: + type: string + example: 'modern, clean, contemporary' + meta_description: + maxLength: 65535 + minLength: 0 + type: string + description: | + A meta description to include. + example: Common Good is a modern brand. + search_keywords: + maxLength: 65535 + minLength: 0 + type: string + description: | + A comma-separated list of keywords that can be used to locate this brand. + example: 'kitchen, laundry, cart, storage' + image_url: + type: string + description: | + Image URL used for this category on the storefront. Images can be uploaded via form file post to `/brands/{brandId}/image`, or by providing a publicly accessible URL in this field. + example: 'https://cdn8.bigcommerce.com/s-12345/product_images/k/your-image-name.png' + x-url: true + custom_url: + title: Custom Url Brand + type: object + properties: + url: + type: string + description: | + Brand URL on the storefront. + example: /shoes + x-url: true + is_customized: + type: boolean + description: | + Returns `true` if the URL has been changed from its default state (the auto-assigned URL that BigCommerce provides). + example: true + description: The custom URL for the brand on the storefront. + description: Common Brand properties. + meta: + $ref: '#/components/schemas/metaEmpty_Full' + description: |- + Brand Response returns for: + * Create Brand + * Get Brand by Id + * Update Brand by Id + example: + data: + id: 50 + name: Common Good + meta_keywords: + - 'modern, clean, contemporary' + meta_description: Common Good is a modern brand + image_url: '' + search_keywords: 'kitchen, laundry, cart, storage' + custom_url: + url: /brands/Common-Good.html + is_customized: false + meta: {} + '207': + $ref: '#/components/responses/General207Status' + '409': + description: Brand was in conflict with another brand. This is the result of duplicate unique fields such as name. + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + '422': + description: 'Brand was not valid. This is the result of missing required fields, or of invalid data. See the response for more details.' + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + x-codegen-request-body-name: Brand + delete: + tags: + - Brands + summary: Delete Brands + description: |- + To delete brand objects, you must include a filter. + + **Required Fields** + - name + + operationId: deleteBrands + parameters: + - name: name + in: query + description: | + Filter items by name. + schema: + type: string + required: + true + - name: page_title + in: query + description: | + Filter items by page_title. + schema: + type: string + responses: + '204': + description: '' + content: {} + parameters: + - $ref: '#/components/parameters/Accept' + '/catalog/brands/{brand_id}': + get: + tags: + - Brands + summary: Get a Brand + description: Returns a single *Brand*. Optional filter parameters can be passed in. + operationId: getBrandById + parameters: + - name: include_fields + in: query + description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' + schema: + type: string + - name: exclude_fields + in: query + description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + title: Brand Response + type: object + properties: + data: + $ref: '#/components/schemas/brand_Full' + meta: + $ref: '#/components/schemas/metaEmpty_Full' + description: |- + Brand Response returns for: + * Create Brand + * Get Brand by Id + * Update Brand by Id + example: + data: + id: 50 + name: Common Good + meta_keywords: + - 'modern, clean, contemporary' + meta_description: Common Good is a modern brand + image_url: '' + search_keywords: 'kitchen, laundry, cart, storage' + custom_url: + url: /brands/Common-Good.html + is_customized: false + meta: {} + '404': + description: | + The resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + put: + tags: + - Brands + summary: Update a Brand + description: |- + Updates a *Brand*. + + **Required Fields** + - None + + **Read-Only Fields** + - id + + To update a *Brand Image*, send a request with an `image_url`. + operationId: updateBrand + parameters: + - $ref: '#/components/parameters/ContentType' + requestBody: + content: + application/json: + schema: + title: Brand + required: + - name + type: object + properties: + id: + type: integer + description: Unique ID of the *Brand*. Read-Only. + readOnly: true + name: + maxLength: 255 + minLength: 1 + type: string + description: |- + The name of the brand. Must be unique. + Required in POST. + example: Common Good + x-required: + - post + - put + page_title: + maxLength: 255 + minLength: 0 + type: string + description: | + The title shown in the browser while viewing the brand. + example: Common Good + meta_keywords: + type: array + description: | + Comma-separated list of meta keywords to include in the HTML. + example: + - 'modern, clean, contemporary' + items: + type: string + meta_description: + maxLength: 65535 + minLength: 0 + type: string + description: | + A meta description to include. + example: Common Good is a modern brand. + search_keywords: + maxLength: 65535 + minLength: 0 + type: string + description: | + A comma-separated list of keywords that can be used to locate this brand. + example: 'kitchen, laundry, cart, storage' + image_url: + type: string + description: | + Image URL used for this category on the storefront. Images can be uploaded via form file post to `/brands/{brandId}/image`, or by providing a publicly accessible URL in this field. + example: 'https://cdn8.bigcommerce.com/s-12345/product_images/k/your-image-name.png' + x-url: true + custom_url: + title: Custom Url Brand + type: object + properties: + url: + type: string + description: | + Brand URL on the storefront. + example: /shoes + x-url: true + is_customized: + type: boolean + description: | + Returns `true` if the URL has been changed from its default state (the auto-assigned URL that BigCommerce provides). + example: true + description: The custom URL for the brand on the storefront. + description: Common Brand properties. + required: true + responses: + '200': + description: '' + content: + application/json: + schema: + title: Brand Response + type: object + properties: + data: + title: Brand + required: + - name + type: object + properties: + id: + type: integer + description: Unique ID of the *Brand*. Read-Only. + readOnly: true + name: + maxLength: 255 + minLength: 1 + type: string + description: |- + The name of the brand. Must be unique. + Required in POST. + example: Common Good + x-required: + - post + - put + page_title: + maxLength: 255 + minLength: 0 + type: string + description: | + The title shown in the browser while viewing the brand. + example: Common Good + meta_keywords: + type: array + description: | + Comma-separated list of meta keywords to include in the HTML. + example: + - 'modern, clean, contemporary' + items: + type: string + meta_description: + maxLength: 65535 + minLength: 0 + type: string + description: | + A meta description to include. + example: Common Good is a modern brand. + search_keywords: + maxLength: 65535 + minLength: 0 + type: string + description: | + A comma-separated list of keywords that can be used to locate this brand. + example: 'kitchen, laundry, cart, storage' + image_url: + type: string + description: | + Image URL used for this category on the storefront. Images can be uploaded via form file post to `/brands/{brandId}/image`, or by providing a publicly accessible URL in this field. + example: 'https://cdn8.bigcommerce.com/s-12345/product_images/k/your-image-name.png' + x-url: true + custom_url: + title: Custom Url Brand + type: object + properties: + url: + type: string + description: | + Brand URL on the storefront. + example: /shoes + x-url: true + is_customized: + type: boolean + description: | + Returns `true` if the URL has been changed from its default state (the auto-assigned URL that BigCommerce provides). + example: true + description: The custom URL for the brand on the storefront. + description: Common Brand properties. + meta: + $ref: '#/components/schemas/metaEmpty_Full' + description: |- + Brand Response returns for: + * Create Brand + * Get Brand by Id + * Update Brand by Id + example: + data: + id: 50 + name: Common Good + meta_keywords: + - 'modern, clean, contemporary' + meta_description: Common Good is a modern brand + image_url: '' + search_keywords: 'kitchen, laundry, cart, storage' + custom_url: + url: /brands/Common-Good.html + is_customized: false + meta: {} + '207': + $ref: '#/components/responses/General207Status' + '404': + description: | + The resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + '409': + description: | + The `Brand` was in conflict with another product. This is the result of duplicate unique values, such as `name`. + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + '422': + description: | + The `Brand` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + x-codegen-request-body-name: brand + delete: + tags: + - Brands + summary: Delete a Brand + description: Deletes a *Brand*. + operationId: deleteBrandById + responses: + '204': + description: '' + content: {} + parameters: + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/BrandIdParam' + '/catalog/brands/{brand_id}/metafields': + get: + tags: + - Metafields + summary: Get All Brand Metafields + description: 'Returns a list of *Brand Metafields*. Optional filter parameters can be passed in. ' + operationId: getBrandMetafieldsByBrandId + parameters: + - name: id + in: query + description: | + Filter items by ID. + schema: + type: integer + - name: 'id:in' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: 'id:not_in' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: 'id:min' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: 'id:max' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: 'id:greater' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: 'id:less' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: page + in: query + description: Specifies the page number in a limited (paginated) list of products. + schema: + type: integer + - name: limit + in: query + description: Controls the number of items per page in a limited (paginated) list of products. + schema: + type: integer + - name: key + in: query + description: | + Filter based on a metafield's key. + schema: + type: string + - name: namespace + in: query + description: Filter based on a metafield's namespace. + schema: + type: string + - name: include_fields + in: query + description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' + schema: + type: string + - name: exclude_fields + in: query + description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + title: Meta Field Collection Response + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/metafield_Full' + meta: + $ref: '#/components/schemas/metaCollection_Full' + example: + data: + - id: 6 + key: Location + value: 4HG + namespace: Warehouse Locations + permission_set: app_only + resource_type: brand + resource_id: 111 + description: Location in the warehouse + date_created: '1973-01-20T21:34:57.903Z' + date_modified: '1990-12-30T00:29:23.515Z' + - id: 7 + key: Brand location + value: 4HG + namespace: Warehouse Locations + permission_set: read + resource_type: brand + resource_id: 111 + description: Location in the warehouse + date_created: '1973-01-20T21:34:57.903Z' + date_modified: '1990-12-30T00:29:23.515Z' + meta: + pagination: + total: 2 + count: 2 + per_page: 50 + current_page: 1 + total_pages: 1 + links: + current: '?page=1&limit=50' + '404': + description: | + The resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + post: + tags: + - Metafields + summary: Create a Brand Metafield + description: |- + Creates a *Brand Metafield*. + + **Required Fields** + - permission_set + - namespace + - key + - value + + **Read-Only Fields** + - id + + **Note:** The maxiumum number of metafields allowed on each order, product, category, variant, or brand is 250 per client ID. For more information, see [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center. + operationId: createBrandMetafield + parameters: + - $ref: '#/components/parameters/ContentType' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/metafield_Base' + required: true + responses: + '200': + description: '' + content: + application/json: + schema: + title: Metafield Response + type: object + properties: + data: + $ref: '#/components/schemas/metafield_Full' + meta: + title: Meta + type: object + properties: {} + description: Empty meta object; may be used later. + examples: + example-1: + value: + data: + id: 4 + key: location_id + value: 'Shelf 3, Bin 5' + namespace: App Namespace + permission_set: app_only + resource_type: brand + resource_id: 137 + description: Where products are located + date_created: '2021-08-06T19:15:35+00:00' + date_modified: '2021-08-06T19:15:35+00:00' + meta: {} + example-2: + value: + data: + id: 6 + key: Location + value: 4HG + namespace: Warehouse Locations + permission_set: app_only + resource_type: category + resource_id: 111 + description: Location in the warehouse. + date_created: '2018-05-07T20:14:17+00:00' + date_modified: '2018-05-07T20:14:17+00:00' + meta: {} + example-3: + value: + data: + id: 4 + key: location_id + value: 'Shelf 3, Bin 5' + namespace: App Namespace + permission_set: app_only + resource_type: brand + resource_id: 137 + description: Where products are located. + date_created: '2021-08-06T19:15:35+00:00' + date_modified: '2021-08-06T19:15:35+00:00' + meta: {} + '409': + description: | + The `Metafield` was in conflict with another `Metafield`. This can be the result of duplicate unique key combination of the app's client id, namespace, key, resource_type, and resource_id. + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + '422': + description: | + The `Metafield` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + x-codegen-request-body-name: Metafield + parameters: + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/BrandIdParam' + '/catalog/brands/{brand_id}/metafields/{metafield_id}': + get: + tags: + - Metafields + summary: Get a Brand Metafields + description: Returns a *Brand Metafield*. Optional filter parameters can be passed in. + operationId: getBrandMetafieldByBrandId + parameters: + - name: metafield_id + in: path + description: | + The ID of the `Metafield`. + required: true + schema: + type: integer + - name: brand_id + in: path + description: | + The ID of the `Brand` to which the resource belongs. + required: true + schema: + type: integer + + - name: include_fields + in: query + description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' + schema: + type: string + - name: exclude_fields + in: query + description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + title: Metafield Response + type: object + properties: + data: + $ref: '#/components/schemas/metafield_Full' + meta: + $ref: '#/components/schemas/metaEmpty_Full' + example: + data: + id: 4 + key: location_id + value: 'Shelf 3, Bin 5' + namespace: App Namespace + permission_set: app_only + resource_type: product + resource_id: 137 + description: Where products are located + date_created: '2021-08-06T19:15:35+00:00' + date_modified: '2021-08-06T19:15:35+00:00' + meta: {} + '404': + description: | + The resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + put: + tags: + - Metafields + summary: Update a Brand Metafield + description: "Updates a *Brand Metafield*.\n\n**Required Fields** \n* none\n\n**Read-Only Fields**\n* id\n* These fields can only be modified by the app (API credentials) that created the metafield:\n\t* namespace\n\t* key\n\t* permission_set\n\n**Usage Notes**\n* Attempting to modify `namespace`, `key`, and `permission_set` fields using a client ID different from the one used to create those metafields will result in a 403 error message.\n* The maxiumum number of metafields allowed on each order, product, category, variant, or brand is 250 per client ID. For more information, see [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center." + operationId: updateBrandMetafield + parameters: + - $ref: '#/components/parameters/ContentType' + - name: metafield_id + in: path + description: | + The ID of the `Metafield`. + required: true + schema: + type: integer + - name: brand_id + in: path + description: | + The ID of the `Brand` to which the resource belongs. + required: true + schema: + type: integer + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/metafield_Base' + required: true + responses: + '200': + description: '' + content: + application/json: + schema: + title: Metafield Response + type: object + properties: + data: + $ref: '#/components/schemas/metafield_Full' + meta: + $ref: '#/components/schemas/metaEmpty_Full' + example: + data: + id: 4 + key: location_id + value: 'Shelf 3, Bin 5' + namespace: App Namespace + permission_set: app_only + resource_type: product + resource_id: 137 + description: Where products are located + date_created: '2021-08-06T19:15:35+00:00' + date_modified: '2021-08-06T19:15:35+00:00' + meta: {} + '404': + description: | + The resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + x-codegen-request-body-name: Metafield + delete: + tags: + - Metafields + summary: Delete a Brand Metafield + description: Deletes a *Brand Metafield*. + operationId: deleteBrandMetafieldById + parameters: + - name: metafield_id + in: path + description: | + The ID of the `Metafield`. + required: true + schema: + type: integer + - name: brand_id + in: path + description: | + The ID of the `Brand` to which the resource belongs. + required: true + schema: + type: integer + responses: + '204': + description: '' + content: {} + parameters: + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/BrandIdParam' + - $ref: '#/components/parameters/MetafieldIdParam' + '/catalog/brands/{brand_id}/image': + post: + tags: + - Images + summary: Create a Brand Image + description: |- + Creates a *Brand Image*. + + **Required Fields** + - image_file: Form posts are the only accepted upload option. + + **Read-Only Fields** + - id + + Only one image at a time can be created. To update a *Brand Image*, use the [Update a brand](/docs/rest-catalog/brands#update-a-brand) endpoint and an `image_url`. + operationId: createBrandImage + parameters: + - $ref: '#/components/parameters/ContentType' + requestBody: + content: + multipart/form-data: + schema: + type: object + properties: + image_file: + type: string + format: binary + responses: + '200': + description: '' + content: + application/json: + schema: + type: object + properties: + data: + type: object + properties: + image_url: + type: string + meta: + $ref: '#/components/schemas/metaEmpty_Full' + example: + data: + image_url: 'https://cdn11.bigcommerce.com/s-{store_hash}/product_images/k/group_1545334669__76009.png' + meta: {} + '400': + description: Bad Request. The requested resource could not be downloaded and may be invalid. Possible reasons include malformed request syntax or the file host blocking requests. + content: + application/json: + schema: + type: object + properties: {} + '404': + description: The resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + '422': + description: 'Image was not valid. This is the result of a missing `image_file` field, or of an incorrect file type. See the response for more details.' + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + delete: + tags: + - Images + summary: Delete a Brand Image + description: Deletes a *Brand Image*. + operationId: deleteBrandImage + responses: + '204': + description: '' + content: {} + parameters: + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/BrandIdParam' +components: + schemas: + brand_Full: + title: brand_Full + required: + - name + type: object + properties: + id: + type: integer + description: Unique ID of the *Brand*. Read-Only. + readOnly: true + name: + maxLength: 255 + minLength: 1 + type: string + description: |- + The name of the brand. Must be unique. + Required in POST. + example: Common Good + x-required: + - post + - put + page_title: + maxLength: 255 + minLength: 0 + type: string + description: | + The title shown in the browser while viewing the brand. + example: Common Good + meta_keywords: + type: array + description: | + Comma-separated list of meta keywords to include in the HTML. + items: + type: string + example: 'modern, clean, contemporary' + meta_description: + maxLength: 65535 + minLength: 0 + type: string + description: | + A meta description to include. + example: Common Good is a modern brand. + search_keywords: + maxLength: 65535 + minLength: 0 + type: string + description: | + A comma-separated list of keywords that can be used to locate this brand. + example: 'kitchen, laundry, cart, storage' + image_url: + type: string + description: | + Image URL used for this category on the storefront. Images can be uploaded via form file post to `/brands/{brandId}/image`, or by providing a publicly accessible URL in this field. + example: 'https://cdn8.bigcommerce.com/s-12345/product_images/k/your-image-name.png' + x-url: true + custom_url: + $ref: '#/components/schemas/customUrl_Full' + description: Common Brand properties. + x-internal: false + metafield_Base: + title: metafield_Base + type: object + description: 'Metafield for products, categories, variants, and brands; the max number of metafields allowed on each is 50. For more information, see [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center.' + x-internal: false + properties: + key: + maxLength: 64 + minLength: 1 + type: string + description: | + The name of the field, for example: `location_id`, `color`. Required for POST. + example: Location + x-required: + - post + value: + maxLength: 65535 + minLength: 1 + type: string + description: | + The value of the field, for example: `1`, `blue`. Required for POST. + example: 4HG + x-required: + - post + namespace: + maxLength: 64 + minLength: 1 + type: string + description: | + Namespace for the metafield, for organizational purposes. This is set by the developer. Required for POST. + example: Warehouse Locations + x-required: + - post + permission_set: + type: string + description: |- + Determines the visibility and writeability of the field by other API consumers. + + |Value|Description + |-|-| + |`app_only`|Private to the app that owns the field| + |`read`|Visible to other API consumers| + |`write`|Open for reading and writing by other API consumers| + |`read_and_sf_access`|Visible to other API consumers, including on storefront| + |`write_and_sf_access`|Open for reading and writing by other API consumers, including on storefront| + enum: + - app_only + - read + - write + - read_and_sf_access + - write_and_sf_access + description: + maxLength: 255 + minLength: 0 + type: string + description: | + Description for the metafields. + example: Location in the warehouse + required: + - permission_set + - namespace + - key + - value + customUrl_Full: + title: customUrl_Full + type: object + properties: + url: + maxLength: 255 + minLength: 0 + type: string + description: | + Product URL on the storefront. + x-required: + - post + - put + x-url: true + is_customized: + type: boolean + description: | + Returns `true` if the URL has been changed from its default state (the auto-assigned URL that BigCommerce provides). + x-required: + - post + - put + description: The custom URL for the product on the storefront. + x-internal: false + metaCollection_Full: + title: metaCollection_Full + type: object + properties: + pagination: + $ref: '#/components/schemas/pagination_Full' + description: 'Data about the response, including pagination and collection totals.' + x-internal: false + pagination_Full: + title: pagination_Full + type: object + properties: + total: + type: integer + description: | + Total number of items in the result set. + example: 36 + count: + type: integer + description: | + Total number of items in the collection response. + example: 36 + per_page: + type: integer + description: | + The amount of items returned in the collection per page, controlled by the limit parameter. + example: 50 + current_page: + type: integer + description: | + The page you are currently on within the collection. + example: 1 + total_pages: + type: integer + description: | + The total number of pages in the collection. + example: 1 + links: + type: object + properties: + previous: + type: string + description: | + Link to the previous page returned in the response. + current: + type: string + description: | + Link to the current page returned in the response. + example: '?page=1&limit=50' + next: + type: string + description: | + Link to the next page returned in the response. + description: | + Pagination links for the previous and next parts of the whole collection. + description: 'Data about the response, including pagination and collection totals.' + x-internal: false + metaEmpty_Full: + type: object + title: Response meta + properties: {} + additionalProperties: true + description: Response metadata. + error_Base: + title: error_Base + type: object + properties: + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + instance: + type: string + description: | + Error payload for the BigCommerce API. + x-internal: false + metafield_Full: + title: metafield_Full + allOf: + - type: object + properties: + id: + type: integer + description: Unique ID of the *Metafield*. Read-Only. + readOnly: true + example: 6 + - $ref: '#/components/schemas/metafield_Base' + - type: object + properties: + resource_type: + type: string + description: | + The type of resource with which the metafield is associated. + example: product + enum: + - category + - brand + - product + - variant + x-required: + - post + resource_id: + maximum: 10000000000 + minimum: 0 + type: integer + description: | + The ID of the resource with which the metafield is associated. + example: 111 + x-required: + - post + date_created: + type: string + description: | + Date and time of the metafield's creation. Read-Only. + readOnly: true + format: date-time + example: '2018-05-07T20:14:17+00:00' + date_modified: + type: string + description: | + Date and time when the metafield was last updated. Read-Only. + readOnly: true + format: date-time + example: '2018-05-07T20:14:17+00:00' + x-internal: false + responses: + General207Status: + description: 'Multi-status. Multiple operations have taken place and the status for each operation can be viewed in the body of the response. Typically indicates that a partial failure has occured, such as when a `POST` or `PUT` request is successful, but saving the URL or inventory data has failed.' + content: + application/json: + schema: + $ref: '#/components/schemas/error_Base' + parameters: + BrandIdParam: + name: brand_id + in: path + description: | + The ID of the `Brand` to which the resource belongs. + required: true + schema: + type: integer + MetafieldIdParam: + name: metafield_id + in: path + description: | + The ID of the `Metafield`. + required: true + schema: + type: integer + Accept: + name: Accept + in: header + required: true + description: 'The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body.' + schema: + type: string + default: 'application/json' + ContentType: + name: Content-Type + in: header + required: true + description: 'The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the request body.' + schema: + type: string + default: 'application/json' + securitySchemes: + X-Auth-Token: + name: X-Auth-Token + description: |- + ### OAuth scopes + + | UI Name | Permission | Parameter | + |:--------|:-----------|:----------| + | Products | modify | `store_v2_products` | + | Products | read-only | `store_v2_products_read_only` | + + ### Authentication header + + | Header | Argument | Description | + |:-------|:---------|:------------| + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | + + ### Further reading + + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). + + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). + + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). + type: apiKey + in: header diff --git a/reference/catalog/categories_catalog.v3.yml b/reference/catalog/categories_catalog.v3.yml new file mode 100644 index 000000000..43996ff1b --- /dev/null +++ b/reference/catalog/categories_catalog.v3.yml @@ -0,0 +1,2355 @@ +openapi: '3.0.3' +info: + title: Catalog - Categories + description: |- + > The Catalog API manages products, categories, brands, bulk pricing rules, and more. To learn more about catalog resources, see the [Catalog Overview](/docs/store-operations/catalog). + + Our Catalog Categories endpoints let you [create individual categories](/docs/rest-catalog/categories#create-a-category) and [modify categories](/docs/rest-catalog/categories#update-a-category) that organize a store's products, as well as [delete categories](/docs/rest-catalog/categories#delete-a-category). + + Category images have their own dedicated [create a category image](/docs/rest-catalog/categories/images#create-a-category-image) and [delete a category image](/docs/rest-catalog/categories/images#delete-a-category-image) endpoints. + + In addition, categories have metafields that you can use to store information structured in key-value pairs; learn more about [creating category metafields](/docs/rest-catalog/categories/metafields#create-a-category-metafield), [updating category metafields](/docs/rest-catalog/categories/metafields#update-a-category-metafield), and [deleting category metafields](/docs/rest-catalog/categories/metafields#delete-a-category-metafield). + + This API family also contains endpoints to [update product sort order](/docs/rest-catalog/categories/sort-order#update-product-sort-order) within a category. + + These endpoints are primarily useful in applications for single storefront stores. To work with categories for an [MSF-enabled store](/docs/storefront/multi-storefront), see [Category Trees](/docs/rest-catalog/category-trees). + + > To learn more about authenticating Catalog endpoints, locate the **Authentication** section at the top of each endpoint, then click **Show Details**. + + ## Resources + + ### Webhooks + Learn more about [Category webhook events](/docs/integrations/webhooks/events#category). + + ### Additional Catalog endpoints + * [Brands](/docs/rest-catalog/brands) + * [Category Trees](/docs/rest-catalog/category-trees) + * [Products](/docs/rest-catalog/products) + * [Product Modifiers](/docs/rest-catalog/product-modifiers) + * [Product Variants](/docs/rest-catalog/product-variants) + * [Product Variant Options](/docs/rest-catalog/product-variant-options) + + termsOfService: 'https://www.bigcommerce.com/terms' + contact: + name: BigCommerce + url: 'https://www.bigcommerce.com' + email: support@bigcommerce.com + version: '' +servers: + - url: 'https://api.bigcommerce.com/stores/{store_hash}/v3' + variables: + store_hash: + default: store_hash + description: Permanent ID of the BigCommerce store. + description: BigCommerce API Gateway +security: + - X-Auth-Token: [] +tags: + - name: Categories + - name: Metafields + - name: Images + - name: Sort Order +paths: + '/catalog/categories': + get: + tags: + - Categories + summary: Get All Categories + description: |- + Returns a list of *Categories*. Optional filter parameters can be passed in. + + **Note:** + The default rate limit for this endpoint is 40 concurrent requests. + operationId: getCategories + parameters: + - name: id + in: query + description: | + Filter items by ID. + schema: + type: integer + - name: 'id:in' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: 'id:not_in' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: 'id:min' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: 'id:max' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: 'id:greater' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: 'id:less' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: name + in: query + description: | + Filter items by name. + schema: + type: string + - name: 'name:like' + in: query + style: form + explode: false + schema: + type: array + items: + type: string + - name: parent_id + in: query + description: 'Filter items by parent_id. If the category is a child or sub category it can be filtered with the parent_id. ' + schema: + type: integer + - name: 'parent_id:in' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: 'parent_id:min' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: 'parent_id:max' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: 'parent_id:greater' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: 'parent_id:less' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: page_title + in: query + description: | + Filter items by page_title. + schema: + type: string + - name: 'page_title:like' + in: query + style: form + explode: false + schema: + type: array + items: + type: string + - name: keyword + in: query + description: 'Filter items by keywords. eg. new, towel, bath' + schema: + type: string + - name: is_visible + in: query + description: 'Filter items by if visible on the storefront. ' + schema: + type: boolean + - name: page + in: query + description: Specifies the page number in a limited (paginated) list of products. + schema: + type: integer + - name: limit + in: query + description: Controls the number of items per page in a limited (paginated) list of products. + schema: + type: integer + - name: include_fields + in: query + description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' + schema: + type: string + - name: exclude_fields + in: query + description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' + schema: + type: string + - name: sort + in: query + description: |- + Controls the sort order of the response, for example, `sort=name`. + + Allowed values: + - `name`: sort categories in alphabetical order by category name. + - `id`: sort in ascending order by category ID. + - `parent_id`: sort in ascending order by the ID of the parent category. + - `sort_order`: sort in ascending order by sort order value. + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + title: Category Base + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Category' + meta: + $ref: '#/components/schemas/metaCollection_Full' + example: + data: + - id: 19 + parent_id: 0 + name: Garden + description: <p>This is the garden description</p> + views: 0 + sort_order: 2 + page_title: page title + meta_keywords: + - meta keyword + meta_description: meta description + layout_file: category.html + image_url: '' + is_visible: true + search_keywords: search keywords + default_product_sort: use_store_settings + custom_url: + url: /garden/ + is_customized: false + - id: 20 + parent_id: 0 + name: Publications + description: '' + views: 0 + sort_order: 4 + page_title: '' + meta_keywords: + - '' + meta_description: '' + layout_file: category_with_facets.html + image_url: '' + is_visible: true + search_keywords: '' + default_product_sort: use_store_settings + custom_url: + url: /publications/ + is_customized: false + - id: 21 + parent_id: 0 + name: Kitchen + description: '' + views: 0 + sort_order: 3 + page_title: '' + meta_keywords: + - '' + meta_description: '' + layout_file: category_with_facets.html + image_url: '' + is_visible: true + search_keywords: '' + default_product_sort: use_store_settings + custom_url: + url: /kitchen/ + is_customized: false + - id: 22 + parent_id: 0 + name: Utility + description: '' + views: 0 + sort_order: 5 + page_title: '' + meta_keywords: + - '' + meta_description: '' + layout_file: category_with_facets.html + image_url: '' + is_visible: true + search_keywords: '' + default_product_sort: use_store_settings + custom_url: + url: /utility/ + is_customized: false + - id: 23 + parent_id: 0 + name: Shop All + description: '' + views: 0 + sort_order: 0 + page_title: '' + meta_keywords: + - '' + meta_description: '' + layout_file: category_with_facets.html + image_url: '' + is_visible: true + search_keywords: '' + default_product_sort: use_store_settings + custom_url: + url: /shop-all/ + is_customized: false + - id: 39 + parent_id: 19 + name: Bath + description: '' + views: 0 + sort_order: 0 + page_title: '' + meta_keywords: + - '' + meta_description: '' + layout_file: category.html + image_url: '' + is_visible: true + search_keywords: '' + default_product_sort: use_store_settings + custom_url: + url: /garden/bath/ + is_customized: false + meta: + pagination: + total: 6 + count: 6 + per_page: 50 + current_page: 1 + total_pages: 1 + links: + current: '?page=1&limit=50' + post: + tags: + - Categories + summary: Create a Category + description: "Creates a *Category*.\n\nUse this endpoint when an API only works with categories of a default BigCommerce storefront (`channel_id=1`). \n\nUse the [Create Categories](/docs/rest-catalog/category-trees/categories#create-categories) endpoint when an API works with categories across different category trees that belong to different storefront channels.\n\n**Required Fields**:\n- `parent_id`: \n\t- To create a child category, set the `parent_id` to the parent category.\n\t- To create a top level category, set the `parent_id` to `0`.\n- `name`\n\n**Read-Only Fields**:\n- `id`\n\n**Limits**:\n- 16,000 categories per store limit.\n- 1,000 categories per product limit.\n- 50 characters category name length.\n- 8 levels of category depth limit.\n- 65,642 characters category description length limit.\n\n **Note:**\n The default rate limit for this endpoint is 40 concurrent requests.\n" + operationId: createCategory + parameters: + - $ref: '#/components/parameters/ContentType' + requestBody: + content: + application/json: + schema: + title: Category + type: object + description: Common Category object properties. + properties: + parent_id: + type: integer + description: |- + The unique numeric ID of the category's parent. This field controls where the category sits in the tree of categories that organize the catalog. + Required in a POST if creating a child category. + example: 2 + x-required: + - post + name: + maxLength: 50 + minLength: 1 + type: string + description: |- + The name displayed for the category. Name is unique with respect to the category's siblings. + Required in a POST. + example: Bath + x-required: + - post + description: + type: string + description: | + The product description, which can include HTML formatting. + example: <p>We offer a wide variety of products perfect for relaxing</p> + views: + type: integer + description: | + Number of views the category has on the storefront. + example: 1050 + sort_order: + maximum: 2147483647 + minimum: -2147483648 + type: integer + description: | + Priority this category will be given when included in the menu and category pages. The lower the number, the closer to the top of the results the category will be. + example: 3 + page_title: + maxLength: 255 + minLength: 0 + type: string + description: | + Custom title for the category page. If not defined, the category name will be used as the meta title. + example: Bath + search_keywords: + maxLength: 255 + minLength: 0 + type: string + description: | + A comma-separated list of keywords that can be used to locate the category when searching the store. + meta_keywords: + type: array + description: | + Custom meta keywords for the category page. If not defined, the store's default keywords will be used. Must post as an array like: ["awesome","sauce"]. + items: + type: string + meta_description: + maxLength: 65535 + minLength: 0 + type: string + description: | + Custom meta description for the category page. If not defined, the store's default meta description will be used. + layout_file: + maxLength: 500 + minLength: 0 + type: string + description: | + A valid layout file. Please refer to [the article on creating category files (Help Center)](https://support.bigcommerce.com/articles/Public/Creating-Custom-Template-Files/). This field is writable only for stores with a Blueprint theme applied. For stores with a Stencil theme applied, see [Custom Template Associations](/docs/rest-content/custom-template-associations). + example: category.html + is_visible: + type: boolean + description: | + Flag to determine whether the category should be displayed to customers browsing the store. If `true`, the category will be displayed. If `false`, the category will be hidden from view. + default_product_sort: + type: string + description: | + Determines how the products are sorted on category page load. + enum: + - use_store_settings + - featured + - newest + - best_selling + - alpha_asc + - alpha_desc + - avg_customer_review + - price_asc + - price_desc + image_url: + type: string + description: | + Image URL used for this category on the storefront. Images can be uploaded using form file post to `/categories/{categoryId}/image`, or by providing a publicly accessible URL in this field. An image extension like .jpg or .png is required. + example: 'https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png' + x-url: true + custom_url: + title: Custom Url Category + type: object + description: The custom URL for the category on the storefront. + properties: + url: + maxLength: 255 + minLength: 0 + type: string + description: | + Category URL on the storefront. + example: /shoes + x-required: + - post + - put + x-url: true + is_customized: + type: boolean + description: | + Returns `true` if the URL has been changed from its default state (the auto-assigned URL that BigCommerce provides). + x-required: + - post + - put + required: + - parent_id + - name + required: true + responses: + '200': + description: '' + content: + application/json: + schema: + title: Category Response + type: object + properties: + data: + $ref: '#/components/schemas/category_Full' + meta: + $ref: '#/components/schemas/metaEmpty_Full' + '207': + description: 'Multiple operations have taken place and the status for each operation can be viewed in the body of the response. Typically indicates that a partial failure has occurred, such as when a `POST` or `PUT` request is successful, but saving the URL has failed.' + content: + application/json: + schema: + $ref: '#/components/schemas/error_Base' + '409': + description: | + The `Category` was in conflict with another category. This is the result of duplicate unique values, such as `name` or `custom_url`. + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + '422': + description: | + The `Category` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + x-codegen-request-body-name: category + delete: + tags: + - Categories + summary: Delete Categories + description: |- + Deletes *Category* objects. At least one filter parameter is required to perform the `DELETE` operation. + + **Usage Notes** + + - Sending a `DELETE`request without specifying a filter parameter will result in a `422` error. + - Sending a `DELETE` request for a category that contains products will result in a `422` error. Move products to a new category by sending a `PUT` request to the `/catalog/products/{product_id}` endpoint before deleting a category. + operationId: deleteCategories + parameters: + - name: id + in: query + description: Filter items by ID. + schema: + type: integer + - name: 'id:in' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: 'id:not_in' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: 'id:min' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: 'id:max' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: 'id:greater' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: 'id:less' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: name + in: query + description: | + Filter items by name. + schema: + type: string + - name: parent_id + in: query + description: 'Filter items by parent_id. If the category is a child or sub category it can be filtered with the parent_id. ' + schema: + type: integer + - name: page_title + in: query + description: | + Filter items by page_title. + schema: + type: string + - name: keyword + in: query + description: 'Filter items by keywords. eg. new, towel, bath' + schema: + type: string + - name: is_visible + in: query + description: 'Filter items by if visible on the storefront. ' + schema: + type: boolean + - name: 'name:like' + in: query + style: form + explode: false + schema: + type: array + items: + type: string + - name: 'parent_id:in' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: 'parent_id:min' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: 'parent_id:max' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: 'parent_id:greater' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: 'parent_id:less' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: 'page_title:like' + in: query + style: form + explode: false + schema: + type: array + items: + type: string + responses: + '204': + description: '' + content: {} + parameters: + - $ref: '#/components/parameters/Accept' + '/catalog/categories/{category_id}': + get: + tags: + - Categories + summary: Get a Category + description: |- + Returns a single *Category*. Optional parameters can be passed in. + + **Note:** + The default rate limit for this endpoint is 40 concurrent requests. + operationId: getCategoryById + parameters: + - name: include_fields + in: query + description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' + schema: + type: string + - name: exclude_fields + in: query + description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + title: Category Response + type: object + properties: + data: + $ref: '#/components/schemas/category_Full' + meta: + $ref: '#/components/schemas/metaEmpty_Full' + '404': + description: | + The resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + put: + tags: + - Categories + summary: Update a Category + description: |- + Updates a *Category*. + + **Required Fields** + * none + + **Read-Only Fields** + - id + + **Note:** + The default rate limit for this endpoint is 40 concurrent requests. + operationId: updateCategory + parameters: + - $ref: '#/components/parameters/ContentType' + requestBody: + content: + application/json: + schema: + title: Category + type: object + description: Common Category object properties. + properties: + id: + type: integer + description: |- + Unique ID of the *Category*. Increments sequentially. + Read-Only. + readOnly: true + parent_id: + type: integer + description: |- + The unique numeric ID of the category's parent. This field controls where the category sits in the tree of categories that organize the catalog. + Required in a POST if creating a child category. + example: 2 + x-required: + - post + name: + maxLength: 50 + minLength: 1 + type: string + description: |- + The name displayed for the category. Name is unique with respect to the category's siblings. + Required in a POST. + example: Bath + x-required: + - post + description: + type: string + description: | + The product description, which can include HTML formatting. + example: <p>We offer a wide variety of products perfect for relaxing</p> + views: + type: integer + description: | + Number of views the category has on the storefront. + example: 1050 + sort_order: + maximum: 2147483647 + minimum: -2147483648 + type: integer + description: | + Priority this category will be given when included in the menu and category pages. The lower the number, the closer to the top of the results the category will be. + example: 3 + page_title: + maxLength: 255 + minLength: 0 + type: string + description: | + Custom title for the category page. If not defined, the category name will be used as the meta title. + example: Bath + search_keywords: + maxLength: 255 + minLength: 0 + type: string + description: | + A comma-separated list of keywords that can be used to locate the category when searching the store. + meta_keywords: + type: array + description: | + Custom meta keywords for the category page. If not defined, the store's default keywords will be used. Must post as an array like: ["awesome","sauce"]. + items: + type: string + meta_description: + maxLength: 65535 + minLength: 0 + type: string + description: | + Custom meta description for the category page. If not defined, the store's default meta description will be used. + layout_file: + maxLength: 500 + minLength: 0 + type: string + description: | + A valid layout file. Please refer to [the article on creating category files (Help Center)](https://support.bigcommerce.com/articles/Public/Creating-Custom-Template-Files/). This field is writable only for stores with a Blueprint theme applied. For stores with a Stencil theme applied, see [Custom Template Associations](/docs/rest-content/custom-template-associations). + example: category.html + is_visible: + type: boolean + description: | + Flag to determine whether the product should be displayed to customers browsing the store. If `true`, the category will be displayed. If `false`, the category will be hidden from view. + default_product_sort: + type: string + description: | + Determines how the products are sorted on category page load. + enum: + - use_store_settings + - featured + - newest + - best_selling + - alpha_asc + - alpha_desc + - avg_customer_review + - price_asc + - price_desc + image_url: + type: string + description: | + Image URL used for this category on the storefront. Images can be uploaded using form file post to `/categories/{categoryId}/image`, or by providing a publicly accessible URL in this field. An image extension like .jpg or .png is required. + example: 'https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png' + x-url: true + custom_url: + title: Custom Url Category + type: object + description: The custom URL for the category on the storefront. + properties: + url: + maxLength: 255 + minLength: 0 + type: string + description: | + Category URL on the storefront. + example: /shoes + x-required: + - post + - put + x-url: true + is_customized: + type: boolean + description: | + Returns `true` if the URL has been changed from its default state (the auto-assigned URL that BigCommerce provides). + x-required: + - post + - put + required: + - parent_id + - name + required: true + responses: + '200': + description: '' + content: + application/json: + schema: + title: Category Response + type: object + properties: + data: + title: Category + type: object + description: Common Category object properties. + properties: + id: + type: integer + description: |- + Unique ID of the *Category*. Increments sequentially. + Read-Only. + readOnly: true + parent_id: + type: integer + description: |- + The unique numeric ID of the category's parent. This field controls where the category sits in the tree of categories that organize the catalog. + Required in a POST if creating a child category. + example: 2 + x-required: + - post + name: + maxLength: 50 + minLength: 1 + type: string + description: |- + The name displayed for the category. Name is unique with respect to the category's siblings. + Required in a POST. + example: Bath + x-required: + - post + description: + type: string + description: | + The product description, which can include HTML formatting. + example: <p>We offer a wide variety of products perfect for relaxing</p> + views: + type: integer + description: | + Number of views the category has on the storefront. + example: 1050 + sort_order: + maximum: 2147483647 + minimum: -2147483648 + type: integer + description: | + Priority this category will be given when included in the menu and category pages. The lower the number, the closer to the top of the results the category will be. + example: 3 + page_title: + maxLength: 255 + minLength: 0 + type: string + description: | + Custom title for the category page. If not defined, the category name will be used as the meta title. + example: Bath + search_keywords: + maxLength: 255 + minLength: 0 + type: string + description: | + A comma-separated list of keywords that can be used to locate the category when searching the store. + meta_keywords: + type: array + description: | + Custom meta keywords for the category page. If not defined, the store's default keywords will be used. Must post as an array like: ["awesome","sauce"]. + items: + type: string + meta_description: + maxLength: 65535 + minLength: 0 + type: string + description: | + Custom meta description for the category page. If not defined, the store's default meta description will be used. + layout_file: + maxLength: 500 + minLength: 0 + type: string + description: | + A valid layout file. Please refer to [the article on creating category files (Help Center)](https://support.bigcommerce.com/articles/Public/Creating-Custom-Template-Files/). This field is writable only for stores with a Blueprint theme applied. For stores with a Stencil theme applied, see [Custom Template Associations](/docs/rest-content/custom-template-associations). + example: category.html + is_visible: + type: boolean + description: | + Flag to determine whether the product should be displayed to customers browsing the store. If `true`, the category will be displayed. If `false`, the category will be hidden from view. + default_product_sort: + type: string + description: | + Determines how the products are sorted on category page load. + enum: + - use_store_settings + - featured + - newest + - best_selling + - alpha_asc + - alpha_desc + - avg_customer_review + - price_asc + - price_desc + image_url: + type: string + description: | + Image URL used for this category on the storefront. Images can be uploaded using form file post to `/categories/{categoryId}/image`, or by providing a publicly accessible URL in this field. An image extension like .jpg or .png is required. + example: 'https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png' + x-url: true + custom_url: + title: Custom Url Category + type: object + description: The custom URL for the category on the storefront. + properties: + url: + maxLength: 255 + minLength: 0 + type: string + description: | + Category URL on the storefront. + example: /shoes + x-required: + - post + - put + x-url: true + is_customized: + type: boolean + description: | + Returns `true` if the URL has been changed from its default state (the auto-assigned URL that BigCommerce provides). + x-required: + - post + - put + required: + - parent_id + - name + meta: + title: Meta + type: object + description: Empty meta object; may be used later. + '207': + $ref: '#/components/responses/General207Status' + '404': + description: The resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + '409': + description: 'The `Category` was in conflict with another category. This is the result of duplicate unique values, such as `name` or `custom_url`.' + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + '422': + description: 'The `Category` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details.' + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + x-codegen-request-body-name: category + delete: + tags: + - Categories + summary: Delete a Category + description: |- + Deletes a *Category*. + + **Note:** + The default rate limit for this endpoint is 40 concurrent requests. + operationId: deleteCategoryById + responses: + '204': + description: '' + content: {} + parameters: + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/CategoryIdParam' + '/catalog/categories/{category_id}/metafields': + get: + tags: + - Metafields + summary: Get All Category Metafields + description: Returns a list of *Metafields* on a *Category*. Optional filter parameters can be passed in. + operationId: getCategoryMetafieldsByCategoryId + parameters: + - name: id + in: query + description: | + Filter items by ID. + schema: + type: integer + - name: 'id:in' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: 'id:not_in' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: 'id:min' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: 'id:max' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: 'id:greater' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: 'id:less' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: page + in: query + description: Specifies the page number in a limited (paginated) list of products. + schema: + type: integer + - name: limit + in: query + description: Controls the number of items per page in a limited (paginated) list of products. + schema: + type: integer + - name: key + in: query + description: | + Filter based on a metafield's key. + schema: + type: string + - name: namespace + in: query + description: Filter based on a metafield's namespace. + schema: + type: string + - name: include_fields + in: query + description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' + schema: + type: string + - name: exclude_fields + in: query + description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + title: Meta Field Collection Response + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/metafield_Full' + meta: + $ref: '#/components/schemas/metaCollection_Full' + example: + data: + - id: 6 + key: Location + value: 4HG + namespace: Warehouse Locations + permission_set: app_only + resource_type: category + resource_id: 111 + description: Location in the warehouse + date_created: '1973-01-20T21:34:57.903Z' + date_modified: '1990-12-30T00:29:23.515Z' + - id: 7 + key: Location + value: 4HG + namespace: Warehouse Locations + permission_set: read + resource_type: category + resource_id: 111 + description: Location in the warehouse + date_created: '1973-01-20T21:34:57.903Z' + date_modified: '1990-12-30T00:29:23.515Z' + meta: + pagination: + total: 2 + count: 2 + per_page: 50 + current_page: 1 + total_pages: 1 + links: + current: '?page=1&limit=50' + '404': + description: | + The resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + post: + tags: + - Metafields + summary: Create a Category Metafield + description: |- + Creates a *Category Metafield*. + + **Required Fields:** + - permission_set + - namespace + - key + - value + + **Read-Only Fields** + - id + + **Note:** The maximum number of metafields allowed on each order, product, category, variant, or brand is 250 per client ID. For more information, see [Platform Limits (Help Center)](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center. + operationId: createCategoryMetafield + parameters: + - $ref: '#/components/parameters/ContentType' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/metafield_Base' + required: true + responses: + '200': + description: '' + content: + application/json: + schema: + title: Metafield Response + type: object + properties: + data: + $ref: '#/components/schemas/metafield_Full' + meta: + $ref: '#/components/schemas/metaEmpty_Full' + example: + data: + id: 4 + key: location_id + value: 'Shelf 3, Bin 5' + namespace: App Namespace + permission_set: app_only + resource_type: category + resource_id: 137 + description: Where products are located + date_created: '2021-08-06T19:15:35+00:00' + date_modified: '2021-08-06T19:15:35+00:00' + meta: {} + '409': + description: | + The `Metafield` was in conflict with another `Metafield`. This can be the result of duplicate, unique key combinations of the app's client id, namespace, key, resource_type, and resource_id. + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + '422': + description: | + The `Metafield` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + x-codegen-request-body-name: Metafield + parameters: + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/CategoryIdParam' + '/catalog/categories/{category_id}/metafields/{metafield_id}': + get: + tags: + - Metafields + summary: Get a Category Metafield + description: Returns a single *Category Metafield*. Optional parameters can be passed in. + operationId: getCategoryMetafieldByCategoryId + parameters: + - name: include_fields + in: query + description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' + schema: + type: string + - name: exclude_fields + in: query + description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + title: Metafield Response + type: object + properties: + data: + $ref: '#/components/schemas/metafield_Full' + meta: + $ref: '#/components/schemas/metaEmpty_Full' + example: + data: + id: 4 + key: location_id + value: 'Shelf 3, Bin 5' + namespace: App Namespace + permission_set: app_only + resource_type: category + resource_id: 137 + description: Where products are located + date_created: '2021-08-06T19:15:35+00:00' + date_modified: '2021-08-06T19:15:35+00:00' + meta: {} + '404': + description: The resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + put: + tags: + - Metafields + summary: Update a Category Metafield + description: "Updates a *Category Metafield*.\n\n**Required Fields**\n* none\n\n**Read-Only Fields**\n* id\n* These fields can only be modified by the app (API credentials) that created the metafield:\n\t* namespace\n\t* key\n\t* permission_set\n\n**Usage Notes**\n* Attempting to modify `namespace`, `key`, and `permission_set` fields using a client ID different from the one used to create those metafields will result in a 403 error message. " + operationId: updateCategoryMetafield + parameters: + - $ref: '#/components/parameters/ContentType' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/metafield_Base' + required: true + responses: + '200': + description: '' + content: + application/json: + schema: + title: Metafield Response + type: object + properties: + data: + $ref: '#/components/schemas/metafield_Full' + meta: + $ref: '#/components/schemas/metaEmpty_Full' + example: + data: + id: 4 + key: location_id + value: 'Shelf 3, Bin 5' + namespace: App Namespace + permission_set: app_only + resource_type: category + resource_id: 137 + description: Where products are located + date_created: '2021-08-06T19:15:35+00:00' + date_modified: '2021-08-06T19:15:35+00:00' + meta: {} + '404': + description: | + The resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + x-codegen-request-body-name: Metafield + delete: + tags: + - Metafields + summary: Delete a Category Metafield + description: Deletes a *Category Metafield*. + operationId: deleteCategoryMetafieldById + responses: + '204': + description: '' + content: {} + parameters: + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/CategoryIdParam' + - $ref: '#/components/parameters/MetafieldIdParam' + '/catalog/categories/{category_id}/image': + post: + tags: + - Images + summary: Create a Category Image + description: |- + Create a *Category Image*. + + **Required Fields** + - image_file: Form posts are the only accepted upload option. + + Only one image at a time can be created. + Limit image size to 1MB. + To update a *Category Image*, use the [Update categories](/docs/rest-catalog/category-trees/categories#update-categories) endpoint and an `image_url`. + operationId: createCategoryImage + parameters: + - $ref: '#/components/parameters/ContentType' + requestBody: + content: + multipart/form-data: + schema: + type: object + properties: + image_file: + type: string + format: binary + responses: + '200': + description: '' + content: + application/json: + schema: + type: object + properties: + data: + type: object + properties: + image_url: + type: string + meta: + $ref: '#/components/schemas/metaEmpty_Full' + example: + data: + image_url: 'https://cdn11.bigcommerce.com/s-{store_hash}/product_images/k/group_1545334669__76009.png' + meta: {} + '400': + description: Bad Request. The requested resource could not be downloaded and may be invalid. Possible reasons include malformed request syntax or the file host blocking requests. + content: + application/json: + schema: + type: object + properties: {} + '404': + description: | + The resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + '422': + description: | + Image was not valid. This is the result of a missing `image_file` field or an incorrect file type. See the response for more details. + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + delete: + tags: + - Images + summary: Delete a Category Image + description: Deletes a *Category Image*. + operationId: deleteCategoryImage + responses: + '204': + description: '' + content: {} + parameters: + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/CategoryIdParam' + '/catalog/categories/{category_id}/products/sort-order': + get: + tags: + - Sort Order + summary: Get Product Sort Order + description: |- + Returns a list of products and their sort order for a specific category. + + **Usage Notes** + * Data pairs are displayed in ascending order based on products' `sort_order` values. + * `null` values are allowed for products without specified `sort_order` values. + * Products with `sort_order` value of `null` will be displayed after products with valid numerical values. + * The priorities for determining product sort order on a storefront are the following: + - Priority 1: Manually specified sort order on Category Level (API). + - Priority 2: Manually specified sort order on Product (Global) Level (UI/API). + - Priority 3: Default sorting by Product ID (newly added products go first) (UI/API). + operationId: getsortorders + responses: + '200': + description: '' + content: + application/json: + schema: + type: array + items: + type: object + properties: + product_id: + type: number + sort_order: + type: integer + '404': + description: The requested category was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/error_Base' + put: + tags: + - Sort Order + summary: Update Product Sort Order + description: Updates sort order of products within a specific category. + operationId: updatesortorder + parameters: + - $ref: '#/components/parameters/ContentType' + requestBody: + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/productSortOrder' + required: false + responses: + '200': + description: '' + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/productSortOrder' + '404': + description: The requested category was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/error_Base' + '422': + description: |- + Unprocessable entity. + + Please verify if all requested products are assigned to the category. + + Please verify if all required fields are present in the request body and are filled with values correctly. + content: + application/json: + schema: + $ref: '#/components/schemas/error_Base' + x-codegen-request-body-name: body + parameters: + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/CategoryIdParam' +components: + schemas: + category_Full: + title: category_Full + type: object + description: Common Category object properties. + x-internal: false + properties: + id: + type: integer + description: |- + Unique ID of the *Category*. Increments sequentially. + Read-Only. + readOnly: true + parent_id: + type: integer + description: |- + The unique numeric ID of the category's parent. This field controls where the category sits in the tree of categories that organize the catalog. + Required in a POST if creating a child category. + example: 2 + x-required: + - post + name: + maxLength: 50 + minLength: 1 + type: string + description: |- + The name displayed for the category. Name is unique with respect to the category's siblings. + Required in a POST. + example: Bath + x-required: + - post + description: + type: string + description: | + The product description, which can include HTML formatting. + example: <p>We offer a wide variety of products perfect for relaxing</p> + views: + type: integer + description: | + Number of views the category has on the storefront. + example: 1050 + sort_order: + maximum: 2147483647 + minimum: -2147483648 + type: integer + description: | + Priority this category will be given when included in the menu and category pages. The lower the number, the closer to the top of the results the category will be. + example: 3 + page_title: + maxLength: 255 + minLength: 0 + type: string + description: | + Custom title for the category page. If not defined, the category name will be used as the meta title. + example: Bath + search_keywords: + maxLength: 255 + minLength: 0 + type: string + description: | + A comma-separated list of keywords that can be used to locate the category when searching the store. + meta_keywords: + type: array + description: | + Custom meta keywords for the category page. If not defined, the store's default keywords will be used. Must post as an array like: ["awesome","sauce"]. + items: + type: string + meta_description: + maxLength: 65535 + minLength: 0 + type: string + description: | + Custom meta description for the category page. If not defined, the store's default meta description will be used. + layout_file: + maxLength: 500 + minLength: 0 + type: string + description: | + A valid layout file. Please refer to [the article on creating category files (Help Center)](https://support.bigcommerce.com/articles/Public/Creating-Custom-Template-Files/). This field is writable only for stores with a Blueprint theme applied. For stores with a Stencil theme applied, see [Custom Template Associations](/docs/rest-content/custom-template-associations). + example: category.html + is_visible: + type: boolean + description: | + Flag to determine whether the product should be displayed to customers browsing the store. If `true`, the category will be displayed. If `false`, the category will be hidden from view. + default_product_sort: + type: string + description: | + Determines how the products are sorted on category page load. + enum: + - use_store_settings + - featured + - newest + - best_selling + - alpha_asc + - alpha_desc + - avg_customer_review + - price_asc + - price_desc + image_url: + type: string + description: | + Image URL used for this category on the storefront. Images can be uploaded using form file post to `/categories/{categoryId}/image`, or by providing a publicly accessible URL in this field. An image extension like .jpg or .png is required. + example: 'https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png' + x-url: true + custom_url: + $ref: '#/components/schemas/customUrl_Full' + required: + - parent_id + - name + metafield_Base: + title: metafield_Base + type: object + description: 'Metafield for products, categories, variants, and brands; the max number of metafields allowed on each is 50. For more information, see [Platform Limits (Help Center)](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center.' + x-internal: false + properties: + key: + maxLength: 64 + minLength: 1 + type: string + description: | + The name of the field, for example: `location_id`, `color`. Required for POST. + example: Location + x-required: + - post + value: + maxLength: 65535 + minLength: 1 + type: string + description: | + The value of the field, for example: `1`, `blue`. Required for POST. + example: 4HG + x-required: + - post + namespace: + maxLength: 64 + minLength: 1 + type: string + description: | + Namespace for the metafield, for organizational purposes. This is set by the developer. Required for POST. + example: Warehouse Locations + x-required: + - post + permission_set: + type: string + description: |- + Determines the visibility and writeability of the field by other API consumers. + + |Value|Description + |-|-| + |`app_only`|Private to the app that owns the field| + |`read`|Visible to other API consumers| + |`write`|Open for reading and writing by other API consumers| + |`read_and_sf_access`|Visible to other API consumers, including on storefront| + |`write_and_sf_access`|Open for reading and writing by other API consumers, including on storefront| + enum: + - app_only + - read + - write + - read_and_sf_access + - write_and_sf_access + description: + maxLength: 255 + minLength: 0 + type: string + description: | + Description for the metafields. + example: Location in the warehouse + required: + - permission_set + - namespace + - key + - value + customUrl_Full: + title: customUrl_Full + type: object + properties: + url: + maxLength: 255 + minLength: 0 + type: string + description: | + Product URL on the storefront. + x-required: + - post + - put + x-url: true + is_customized: + type: boolean + description: | + Returns `true` if the URL has been changed from its default state (the auto-assigned URL that BigCommerce provides). + x-required: + - post + - put + description: The custom URL for the product on the storefront. + x-internal: false + metaCollection_Full: + title: metaCollection_Full + type: object + properties: + pagination: + $ref: '#/components/schemas/pagination_Full' + description: 'Data about the response, including pagination and collection totals.' + x-internal: false + pagination_Full: + title: pagination_Full + type: object + properties: + total: + type: integer + description: | + Total number of items in the result set. + example: 36 + count: + type: integer + description: | + Total number of items in the collection response. + example: 36 + per_page: + type: integer + description: | + The amount of items returned in the collection per page, controlled by the limit parameter. + example: 50 + current_page: + type: integer + description: | + The page you are currently on within the collection. + example: 1 + total_pages: + type: integer + description: | + The total number of pages in the collection. + example: 1 + links: + type: object + properties: + previous: + type: string + description: | + Link to the previous page returned in the response. + current: + type: string + description: | + Link to the current page returned in the response. + example: '?page=1&limit=50' + next: + type: string + description: | + Link to the next page returned in the response. + description: | + Pagination links for the previous and next parts of the whole collection. + description: 'Data about the response, including pagination and collection totals.' + x-internal: false + metaEmpty_Full: + type: object + title: Response meta + properties: {} + additionalProperties: true + description: Response metadata. + error_Base: + title: error_Base + type: object + properties: + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + instance: + type: string + description: | + Error payload for the BigCommerce API. + x-internal: false + metafield_Full: + title: metafield_Full + allOf: + - type: object + properties: + id: + type: integer + description: Unique ID of the *Metafield*. Read-Only. + readOnly: true + example: 6 + - $ref: '#/components/schemas/metafield_Base' + - type: object + properties: + resource_type: + type: string + description: | + The type of resource with which the metafield is associated. + example: product + enum: + - category + - brand + - product + - variant + x-required: + - post + resource_id: + maximum: 10000000000 + minimum: 0 + type: integer + description: | + The ID of the resource with which the metafield is associated. + example: 111 + x-required: + - post + date_created: + type: string + description: | + Date and time of the metafield's creation. Read-Only. + readOnly: true + format: date-time + example: '2018-05-07T20:14:17+00:00' + date_modified: + type: string + description: | + Date and time when the metafield was last updated. Read-Only. + readOnly: true + format: date-time + example: '2018-05-07T20:14:17+00:00' + x-internal: false + productSortOrder: + title: productSortOrder + required: + - product_id + - sort_order + type: object + properties: + product_id: + minimum: 1 + type: integer + description: The ID of the associated product. + example: 99 + sort_order: + minimum: 0 + type: integer + example: 4 + description: The relative priority of the product among other products inside the category. + x-internal: false + Category: + x-tags: + - Models + title: Category + allOf: + - $ref: '#/components/schemas/id' + - $ref: '#/components/schemas/parent_id' + - $ref: '#/components/schemas/name' + - $ref: '#/components/schemas/description' + - $ref: '#/components/schemas/views' + - $ref: '#/components/schemas/sort_order' + - $ref: '#/components/schemas/page_title' + - $ref: '#/components/schemas/meta_keywords' + - $ref: '#/components/schemas/meta_description' + - $ref: '#/components/schemas/layout_file' + - $ref: '#/components/schemas/image_url' + - $ref: '#/components/schemas/is_visible' + - $ref: '#/components/schemas/search_keywords' + - $ref: '#/components/schemas/default_product_sort' + - type: object + properties: + custom_url: + $ref: '#/components/schemas/Url' + x-examples: {} + Url: + type: object + properties: + url: + type: string + is_customized: + type: boolean + x-tags: + - Models + default_product_sort: + title: default_product_sort + type: object + properties: + default_product_sort: + type: string + description: | + Determines how the products are sorted on category page load. + enum: + - use_store_settings + - featured + - newest + - best_selling + - alpha_asc + - alpha_desc + - avg_customer_review + - price_asc + - price_desc + name: + title: name + type: object + properties: + name: + maxLength: 50 + minLength: 1 + type: string + description: |- + The name displayed for the category. Name is unique with respect to the category's siblings. + Required in a POST. + example: Bath + description: + title: description + type: object + properties: + description: + type: string + description: | + The product description, which can include HTML formatting. + example: <p>We offer a wide variety of products perfect for relaxing</p> + views: + title: views + type: object + properties: + views: + type: integer + description: | + Number of views the category has on the storefront. + example: 1050 + sort_order: + title: sort_order + type: object + properties: + sort_order: + type: integer + description: | + Priority this category will be given when included in the menu and category pages. The lower the number, the closer to the top of the results the category will be. + example: 3 + page_title: + title: page_title + type: object + properties: + page_title: + type: string + description: | + Custom title for the category page. If not defined, the category name will be used as the meta title. + example: Bath + search_keywords: + title: search_keywords + type: object + properties: + search_keywords: + type: string + description: | + A comma-separated list of keywords that can be used to locate the category when searching the store. + meta_keywords: + title: meta_keywords + type: object + properties: + meta_keywords: + type: array + description: | + Custom meta keywords for the category page. If not defined, the store's default keywords will be used. Must post as an array like: ["awesome","sauce"]. + items: + type: string + layout_file: + title: layout_file + type: object + properties: + layout_file: + maxLength: 500 + minLength: 0 + type: string + description: | + A valid layout file. Please refer to [the article on creating category files (Help Center)](https://support.bigcommerce.com/articles/Public/Creating-Custom-Template-Files/). This field is writable only for stores with a Blueprint theme applied. For stores with a Stencil theme applied, see [Custom Template Associations](/docs/rest-content/custom-template-associations). + example: category.html + is_visible: + title: is_visible + type: object + properties: + is_visible: + type: boolean + description: | + Flag to determine whether the product should be displayed to customers browsing the store. If `true`, the category will be displayed. If `false`, the category will be hidden from view. + image_url: + title: image_url + type: object + properties: + image_url: + type: string + description: | + Image URL used for this category on the storefront. Images can be uploaded using form file post to `/categories/{categoryId}/image`, or by providing a publicly accessible URL in this field. An image extension like .jpg or .png is required. + example: 'https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png' + x-url: true + meta_description: + title: meta_description + type: object + properties: + meta_description: + maxLength: 65535 + minLength: 0 + type: string + description: | + Custom meta description for the category page. If not defined, the store's default meta description will be used. + id: + title: id + type: object + properties: + id: + type: integer + description: |- + Unique ID of the *Category*. Increments sequentially. + Read-Only. + readOnly: true + parent_id: + title: parent_id + type: object + properties: + parent_id: + type: integer + description: |- + The unique numeric ID of the category's parent. This field controls where the category sits in the tree of categories that organize the catalog. + Required in a POST if creating a child category. + example: 2 + responses: + General207Status: + description: 'Multi-status. Multiple operations have taken place and the status for each operation can be viewed in the body of the response. Typically indicates that a partial failure has occurred, such as when a `POST` or `PUT` request is successful, but saving the URL or inventory data has failed.' + content: + application/json: + schema: + $ref: '#/components/schemas/error_Base' + parameters: + CategoryIdParam: + name: category_id + in: path + description: | + The ID of the `Category` to which the resource belongs. + required: true + schema: + type: integer + MetafieldIdParam: + name: metafield_id + in: path + description: | + The ID of the `Metafield`. + required: true + schema: + type: integer + Accept: + name: Accept + in: header + required: true + description: 'The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body.' + schema: + type: string + default: 'application/json' + ContentType: + name: Content-Type + in: header + required: true + description: 'The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the request body.' + schema: + type: string + default: 'application/json' + securitySchemes: + X-Auth-Token: + name: X-Auth-Token + description: |- + ### OAuth scopes + + | UI Name | Permission | Parameter | + |:--------|:-----------|:----------| + | Products | modify | `store_v2_products` | + | Products | read-only | `store_v2_products_read_only` | + + ### Authentication header + + | Header | Argument | Description | + |:-------|:---------|:------------| + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | + + ### Further reading + + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). + + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). + + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). + type: apiKey + in: header diff --git a/reference/catalog/category-trees_catalog.v3.yml b/reference/catalog/category-trees_catalog.v3.yml new file mode 100644 index 000000000..3ccc45690 --- /dev/null +++ b/reference/catalog/category-trees_catalog.v3.yml @@ -0,0 +1,1132 @@ +openapi: '3.0.3' +info: + title: Catalog - Category Trees + description: |- + > The Catalog API manages products, categories, brands, bulk pricing rules, and more. To learn more about catalog resources, see the [Catalog Overview](/docs/store-operations/catalog). + + Our Catalog Category Trees endpoints are the more modern and performant counterparts to the [Categories endpoints](/docs/rest-catalog/categories). Although the Category Trees endpoints and objects are designed to center an MSF-compatible, [multi-tenant category tree architecture](#categories), the endpoints work just as well in a single storefront context. + + The Category Trees endpoints let you [get the Categories for a specific tree](/docs/rest-catalog/category-trees/categories#get-a-category-tree), and [bulk create](/docs/rest-catalog/category-trees/categories#create-categories), [bulk update](/docs/rest-catalog/category-trees/categories#update-categories), and [bulk delete](/docs/rest-catalog/category-trees/categories#delete-categories) Categories. You can also [bulk update the properties of Category Trees](/docs/rest-catalog/category-trees#upsert-category-trees), which includes changing the channels to which a Tree is assigned. + + The terms "category tree" and "catalog tree" are used interchangeably throughout the documentation. + + > To learn more about authenticating Catalog endpoints, locate the **Authentication** section at the top of each endpoint, then click **Show Details**. + + ## Resources + + ### Webhooks + Learn more about [Category Tree webhook events](/docs/integrations/webhooks/events/channels#category-trees). + + ### Additional Catalog endpoints + * [Brands](/docs/rest-catalog/brands) + * [Categories](/docs/rest-catalog/categories) + * [Products](/docs/rest-catalog/products) + * [Product Modifiers](/docs/rest-catalog/product-modifiers) + * [Product Variants](/docs/rest-catalog/product-variants) + * [Product Variant Options](/docs/rest-catalog/product-variant-options) + + termsOfService: 'https://www.bigcommerce.com/terms' + contact: + name: BigCommerce + url: 'https://www.bigcommerce.com' + email: support@bigcommerce.com + version: '' +servers: + - url: 'https://api.bigcommerce.com/stores/{store_hash}/v3' + variables: + store_hash: + default: store_hash + description: Permanent ID of the BigCommerce store. + description: BigCommerce API Gateway +security: + - X-Auth-Token: [] +tags: + - name: Category Trees + - name: Categories +paths: + '/catalog/trees/categories': + get: + summary: Get All Categories + description: |- + Returns a list of categories. + + To get a specific category in a tree, provide a category ID. + tags: + - Categories + parameters: + - name: 'category_uuid:in' + in: query + schema: + type: string + - name: 'category_uuid:not_in' + in: query + schema: + type: string + - name: 'category_id:in' + in: query + schema: + type: string + - name: 'category_id:not_in' + in: query + schema: + type: string + - name: 'tree_id:in' + in: query + schema: + type: string + - name: 'tree_id:not_in' + in: query + schema: + type: string + - name: 'parent_id:in' + in: query + schema: + type: string + - name: 'parent_id:not_in' + in: query + schema: + type: string + - name: name + in: query + schema: + type: string + - name: 'name:like' + in: query + schema: + type: string + - name: page_title + in: query + schema: + type: string + - name: 'page_title:like' + in: query + schema: + type: string + - name: keyword + in: query + schema: + type: string + - name: is_visible + in: query + schema: + type: boolean + - name: page + in: query + schema: + type: integer + - name: limit + in: query + schema: + type: integer + - name: include_fields + in: query + schema: + type: string + - name: exclude_fields + in: query + schema: + type: string + responses: + '200': + description: List of categories. + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Category' + meta: + $ref: '#/components/schemas/MetaPagination' + examples: + example-1: + value: + data: + - id: 0 + parent_id: 2 + name: Bath + description: <p>We offer a wide variety of products perfect for relaxing</p> + views: 1050 + sort_order: 3 + page_title: Bath + meta_keywords: + - string + meta_description: string + layout_file: category.html + image_url: 'https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png' + is_visible: true + search_keywords: string + default_product_sort: use_store_settings + url: + path: string + is_customized: true + meta: + pagination: + total: 246 + count: 5 + per_page: 5 + current_page: 1 + total_pages: 50 + links: + previous: '?limit=5&page=1' + current: '?limit=5&page=2' + next: '?limit=5&page=3' + '400': + description: Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorRequest' + '500': + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorRequest' + operationId: getAllCategories + post: + summary: Create Categories + description: |- + Creates new categories. + + Creating a category requires: + - `name` + - `url` + - `tree_id` or `parent_id` + parameters: + - $ref: '#/components/parameters/ContentType' + tags: + - Categories + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateCategories' + responses: + '201': + description: Created + content: + application/json: + schema: + $ref: '#/components/schemas/SuccessResponse' + '207': + description: Multi-Status + content: + application/json: + schema: + $ref: '#/components/schemas/PartialSuccessResponse' + '400': + description: Bad Request + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorRequest' + '422': + description: 'The Category was not valid. This is the result of missing required fields, or of invalid data. See the response for more details.' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorRequest' + operationId: createCategories + put: + summary: Update Categories + description: |- + Updates existing categories. + + To update a specific category in a tree, provide a category id. + parameters: + - $ref: '#/components/parameters/ContentType' + tags: + - Categories + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateCategories' + responses: + '200': + description: OK + '204': + description: No Content + content: + application/json: + schema: + $ref: '#/components/schemas/SuccessNoContentResponse' + '207': + description: Partial success + content: + application/json: + schema: + $ref: '#/components/schemas/PartialSuccessNoContentResponse' + '400': + description: Bad request + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorRequest' + '422': + description: 'The Category was not valid. This is the result of missing required fields, or of invalid data. See the response for more details.' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + '500': + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorRequest' + operationId: updateCategories + delete: + summary: Delete Categories + description: |- + Deletes categories. + + To delete a specific category in a tree, provide a category ID. + tags: + - Categories + parameters: + - name: 'category_uuid:in' + in: query + schema: + type: string + - name: 'category_id:in' + in: query + schema: + type: string + - name: 'tree_id:in' + in: query + schema: + type: string + - name: 'parent_id:in' + in: query + schema: + type: string + responses: + '204': + description: Categories are deleted + content: + application/json: + schema: + $ref: '#/components/schemas/SuccessNoContentResponse' + '400': + description: Bad request + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorRequest' + '500': + description: Server error + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorRequest' + operationId: deleteTreeCategories + parameters: + - $ref: '#/components/parameters/Accept' + '/catalog/trees': + get: + summary: Get All Category Trees + description: Returns a list of *Category Trees*. + operationId: GetCategoryTrees + parameters: + - name: 'id:in' + in: query + schema: + type: string + - name: 'channel_id:in' + in: query + schema: + type: string + responses: + '200': + description: List of category trees. + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Tree' + meta: + $ref: '#/components/schemas/MetaPaginationObject' + example: + data: + - id: 0 + name: string + channels: + - 0 + meta: + pagination: + total: 246 + count: 5 + per_page: 5 + current_page: 1 + total_pages: 50 + links: + next: '?limit=5&page=2' + current: '?limit=5&page=1' + tags: + - Category Trees + put: + summary: Upsert Category Trees + description: | + Upserts *Category Trees*. + + This single endpoint updates and creates category trees. If a tree object contains an ID, it is processed as an update operation using that ID. If you do not provide an ID, a new tree is created. The category tree `name` field is required to create trees, but is not required on the update. + + **Usage Notes** + * `channel_id` is required to create a *Category Tree*. You can assign one `channel_id` to one category tree. + parameters: + - $ref: '#/components/parameters/ContentType' + operationId: UpsertCategoryTrees + requestBody: + required: true + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Tree_req' + example: + - id: 0 + name: string + channels: + - 0 + responses: + '200': + description: Created a category tree. + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Tree' + meta: + $ref: '#/components/schemas/metaEmpty_Full' + example: + data: + - id: 0 + name: string + channels: + - 0 + meta: {} + '422': + description: The Channel was not valid. See the response for more details. + content: + application/json: + schema: + $ref: '#/components/schemas/beta4ErrorResponse' + example: + status: 0 + title: string + type: string + instance: string + errors: + additionalProp1: string + additionalProp2: string + additionalProp3: string + tags: + - Category Trees + delete: + summary: Delete Category Trees + description: Deletes *Category Trees*. A filter must be supplied with the endpoint. + operationId: DeleteCategoryTrees + parameters: + - name: 'id:in' + in: query + schema: + type: string + responses: + '204': + description: Deleted + tags: + - Category Trees + parameters: + - $ref: '#/components/parameters/Accept' + '/catalog/trees/{tree_id}/categories': + get: + summary: Get a Category Tree + description: Returns a *Category Tree*. + operationId: GetCategoryTreeByTreeId + parameters: + - name: depth + description: Max depth for a tree of categories. + in: query + schema: + type: integer + responses: + '200': + description: Categories tree + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/CategoryNode' + meta: + $ref: '#/components/schemas/metaEmpty_Full' + example: + data: + - id: 0 + parent_id: 0 + depth: 0 + path: + - 0 + name: string + is_visible: true + children: + - string + meta: + type: object + properties: {} + description: Empty meta object; reserved for use later. + '404': + description: The tree was not found. + content: + application/json: + schema: + $ref: '#/components/schemas/beta4ErrorResponse' + example: + status: 0 + title: string + type: string + instance: string + errors: + additionalProp1: string + additionalProp2: string + additionalProp3: string + tags: + - Categories + parameters: + - $ref: '#/components/parameters/Accept' + - schema: + type: string + name: tree_id + in: path + required: true +components: + schemas: + metaEmpty_Full: + type: object + title: Response meta + properties: {} + additionalProperties: true + description: Response metadata. + DetailedErrors: + title: DetailedErrors + description: Each key-value pair describes a failure or partial success case. + type: object + properties: {} + additionalProperties: true + x-internal: false + CreateCategories: + type: array + items: + allOf: + - $ref: '#/components/schemas/TreeIdCreateData' + - $ref: '#/components/schemas/ParentIdCreateData' + - $ref: '#/components/schemas/CategoryDataPOST' + x-tags: + - Models + title: Create Categories + UpdateCategories: + x-tags: + - Models + type: array + items: + allOf: + - $ref: '#/components/schemas/TreeIdUpdateData' + - $ref: '#/components/schemas/CategoryIdUpdateData' + - $ref: '#/components/schemas/CategoryUuidData' + - $ref: '#/components/schemas/ParentIdUpdateData' + - $ref: '#/components/schemas/CategoryDataPUT' + Category: + x-tags: + - Models + title: Category + allOf: + - $ref: '#/components/schemas/id' + - $ref: '#/components/schemas/parent_id' + - $ref: '#/components/schemas/name' + - $ref: '#/components/schemas/description' + - $ref: '#/components/schemas/views' + - $ref: '#/components/schemas/sort_order' + - $ref: '#/components/schemas/page_title' + - $ref: '#/components/schemas/meta_keywords' + - $ref: '#/components/schemas/meta_description' + - $ref: '#/components/schemas/layout_file' + - $ref: '#/components/schemas/image_url' + - $ref: '#/components/schemas/is_visible' + - $ref: '#/components/schemas/search_keywords' + - $ref: '#/components/schemas/default_product_sort' + - type: object + properties: + url: + $ref: '#/components/schemas/Url' + x-examples: {} + CategoryUuidData: + type: object + x-tags: + - Models + properties: + category_uuid: + type: string + format: uuid + title: category_uuid + CategoryIdUpdateData: + type: object + properties: + category_id: + type: integer + required: + - category_id + x-tags: + - Models + ParentIdCreateData: + type: object + properties: + parent_id: + type: integer + required: + - parent_id + x-tags: + - Models + TreeIdCreateData: + type: object + properties: + tree_id: + type: integer + required: + - tree_id + x-tags: + - Models + ParentIdUpdateData: + type: object + properties: + parent_id: + type: integer + x-tags: + - Models + TreeIdUpdateData: + type: object + x-tags: + - Models + properties: + tree_id: + type: integer + CategoryData: + allOf: + - type: object + properties: + name: + type: string + description: + type: string + views: + type: integer + sort_order: + type: integer + page_title: + type: string + search_keywords: + type: string + meta_keywords: + type: array + items: + type: string + meta_description: + type: string + layout_file: + type: string + is_visible: + type: boolean + image_url: + type: string + url: + $ref: '#/components/schemas/Url' + CategoryDataPUT: + allOf: + - $ref: '#/components/schemas/CategoryData' + - $ref: '#/components/schemas/default_product_sort' + CategoryDataPOST: + allOf: + - $ref: '#/components/schemas/CategoryData' + - $ref: '#/components/schemas/default_product_sort' + required: + - name + - url + Url: + type: object + properties: + path: + type: string + is_customized: + type: boolean + x-tags: + - Models + MetaPagination: + type: object + properties: + pagination: + type: object + properties: + total: + type: integer + example: 246 + minimum: 0 + count: + type: integer + example: 5 + minimum: 0 + per_page: + type: integer + example: 5 + minimum: 0 + current_page: + type: integer + example: 1 + minimum: 1 + total_pages: + type: integer + example: 50 + minimum: 0 + links: + type: object + properties: + previous: + type: string + example: '?limit=5&page=1' + current: + type: string + example: '?limit=5&page=2' + next: + type: string + example: '?limit=5&page=3' + x-tags: + - Models + ErrorRequest: + type: object + properties: + errors: + type: array + items: + $ref: '#/components/schemas/ErrorBasic' + x-tags: + - Models + ErrorBasic: + type: object + properties: + status: + description: | + The HTTP status code. + type: integer + title: + description: | + The error title describing the particular error. + type: string + type: + type: string + x-tags: + - Models + ErrorAdditional: + type: object + properties: + errors: + $ref: '#/components/schemas/DetailedErrors' + x-tags: + - Models + MetaError: + allOf: + - $ref: '#/components/schemas/ErrorBasic' + - $ref: '#/components/schemas/ErrorAdditional' + x-tags: + - Models + MetaData: + type: object + properties: + total: + type: integer + success: + type: integer + failed: + type: integer + x-tags: + - Models + SuccessNoContentResponse: + type: object + properties: + meta: + $ref: '#/components/schemas/MetaData' + x-tags: + - Models + PartialSuccessNoContentResponse: + type: object + properties: + errors: + $ref: '#/components/schemas/MetaError' + meta: + $ref: '#/components/schemas/MetaData' + x-tags: + - Models + PartialSuccessResponse: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Category' + meta: + $ref: '#/components/schemas/MetaData' + x-tags: + - Models + SuccessResponse: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Category' + errors: + $ref: '#/components/schemas/MetaError' + meta: + $ref: '#/components/schemas/MetaData' + x-tags: + - Models + ErrorResponse: + type: object + properties: + errors: + $ref: '#/components/schemas/MetaError' + meta: + $ref: '#/components/schemas/MetaData' + x-tags: + - Models + Tree: + type: object + properties: + id: + type: integer + name: + type: string + minLength: 1 + maxLength: 255 + channels: + type: array + items: + type: integer + x-tags: + - Models + Tree_req: + type: object + properties: + id: + type: integer + name: + type: string + minLength: 1 + maxLength: 255 + channels: + type: array + items: + type: integer + x-tags: + - Models + CategoryNode: + type: object + properties: + id: + type: integer + parent_id: + type: integer + depth: + type: integer + path: + type: array + items: + type: integer + name: + type: string + is_visible: + type: boolean + children: + type: array + items: + $ref: '#/components/schemas/CategoryNode' + x-tags: + - Models + MetaPaginationObject: + type: object + properties: + pagination: + type: object + properties: + total: + type: integer + example: 246 + minimum: 0 + count: + type: integer + example: 5 + minimum: 0 + per_page: + type: integer + example: 5 + minimum: 0 + current_page: + type: integer + example: 1 + minimum: 1 + total_pages: + type: integer + example: 50 + minimum: 0 + links: + type: object + properties: + next: + type: string + example: '?limit=5&page=2' + current: + type: string + example: '?limit=5&page=1' + x-tags: + - Models + beta4DetailedErrors: + type: object + properties: {} + additionalProperties: true + x-tags: + - Models + BaseError: + type: object + description: | + Error payload for the BigCommerce API. + properties: + status: + description: | + The HTTP status code. + type: integer + title: + description: | + The error title describing the particular error. + type: string + type: + type: string + instance: + type: string + x-tags: + - Models + beta4ErrorResponse: + allOf: + - $ref: '#/components/schemas/BaseError' + - type: object + properties: + errors: + $ref: '#/components/schemas/beta4DetailedErrors' + x-tags: + - Models + default_product_sort: + title: default_product_sort + type: object + properties: + default_product_sort: + type: string + description: | + Determines how the products are sorted on category page load. + enum: + - use_store_settings + - featured + - newest + - best_selling + - alpha_asc + - alpha_desc + - avg_customer_review + - price_asc + - price_desc + name: + title: name + type: object + properties: + name: + maxLength: 50 + minLength: 1 + type: string + description: |- + The name displayed for the category. Name is unique with respect to the category's siblings. + Required in a POST. + example: Bath + description: + title: description + type: object + properties: + description: + type: string + description: | + The product description, which can include HTML formatting. + example: <p>We offer a wide variety of products perfect for relaxing</p> + views: + title: views + type: object + properties: + views: + type: integer + description: | + Number of views the category has on the storefront. + example: 1050 + sort_order: + title: sort_order + type: object + properties: + sort_order: + type: integer + description: | + Priority this category will be given when included in the menu and category pages. The lower the number, the closer to the top of the results the category will be. + example: 3 + page_title: + title: page_title + type: object + properties: + page_title: + type: string + description: | + Custom title for the category page. If not defined, the category name will be used as the meta title. + example: Bath + search_keywords: + title: search_keywords + type: object + properties: + search_keywords: + type: string + description: | + A comma-separated list of keywords that can be used to locate the category when searching the store. + meta_keywords: + title: meta_keywords + type: object + properties: + meta_keywords: + type: array + description: | + Custom meta keywords for the category page. If not defined, the store's default keywords will be used. Must post as an array like: ["awesome","sauce"]. + items: + type: string + layout_file: + title: layout_file + type: object + properties: + layout_file: + maxLength: 500 + minLength: 0 + type: string + description: | + A valid layout file. (Please refer to [this article](https://support.bigcommerce.com/articles/Public/Creating-Custom-Template-Files/) on creating category files.) This field is writable only for stores with a Blueprint theme applied. + example: category.html + is_visible: + title: is_visible + type: object + properties: + is_visible: + type: boolean + description: | + Flag to determine whether the product should be displayed to customers browsing the store. If `true`, the category will be displayed. If `false`, the category will be hidden from view. + image_url: + title: image_url + type: object + properties: + image_url: + type: string + description: | + Image URL used for this category on the storefront. Images can be uploaded via form file post to `/categories/{categoryId}/image`, or by providing a publicly accessible URL in this field. + example: 'https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png' + x-url: true + meta_description: + title: meta_description + type: object + properties: + meta_description: + maxLength: 65535 + minLength: 0 + type: string + description: | + Custom meta description for the category page. If not defined, the store's default meta description will be used. + id: + title: id + type: object + properties: + id: + type: integer + description: |- + Unique ID of the *Category*. Increments sequentially. + Read-Only. + readOnly: true + parent_id: + title: parent_id + type: object + properties: + parent_id: + type: integer + description: |- + The unique numeric ID of the category's parent. This field controls where the category sits in the tree of categories that organize the catalog. + Required in a POST if creating a child category. + example: 2 + parameters: + Accept: + name: Accept + in: header + required: true + description: 'The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body.' + schema: + type: string + default: 'application/json' + ContentType: + name: Content-Type + in: header + required: true + description: 'The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the request body.' + schema: + type: string + default: 'application/json' + securitySchemes: + X-Auth-Token: + name: X-Auth-Token + description: |- + ### OAuth scopes + + | UI Name | Permission | Parameter | + |:--------|:-----------|:----------| + | Products | modify | `store_v2_products` | + | Products | read-only | `store_v2_products_read_only` | + + ### Authentication header + + | Header | Argument | Description | + |:-------|:---------|:------------| + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | + + ### Further reading + + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). + + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). + + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). + type: apiKey + in: header diff --git a/reference/catalog/product-modifiers_catalog.v3.yml b/reference/catalog/product-modifiers_catalog.v3.yml new file mode 100644 index 000000000..d3978eb96 --- /dev/null +++ b/reference/catalog/product-modifiers_catalog.v3.yml @@ -0,0 +1,2838 @@ +openapi: '3.0.3' +info: + title: Catalog - Product Modifiers + description: |- + > The Catalog API manages products, categories, brands, bulk pricing rules, and more. To learn more about catalog resources, see the [Catalog Overview](/docs/store-operations/catalog). + + Product Modifiers represent choices that the shopper can make to change how the merchant customizes or adds on to the product. Examples include shipping insurance, monograms, custom inseam length, and a color selection for an unfinished product. + + Modifier values do not change which item is picked in a warehouse, but they change what happens to that item between the warehouse shelf and the shopper taking possession of their order. + + Critically, Modifier values do not change which Product Variant is fulfilled. You cannot track inventory for combinations of Modifier values. + + You can add an adjuster to a Modifier value to override the underlying Product Variant's properties, such as price, weight, and shipping rules. Not all Modifier types are compatible with adjusters. + + > To learn more about authenticating Catalog endpoints, locate the **Authentication** section at the top of each endpoint, then click **Show Details**. + + ## Resources + + ### Webhooks + Learn more about [Product webhook events](/docs/integrations/webhooks/events#products). + + ### Additional Catalog endpoints + * [Brands](/docs/rest-catalog/brands) + * [Categories](/docs/rest-catalog/categories) + * [Category Trees](/docs/rest-catalog/category-trees) + * [Products](/docs/rest-catalog/products) + * [Product Variants](/docs/rest-catalog/product-variants) + * [Product Variant Options](/docs/rest-catalog/product-variant-options) + + termsOfService: 'https://www.bigcommerce.com/terms' + contact: + name: BigCommerce + url: 'https://www.bigcommerce.com' + email: support@bigcommerce.com + version: '' +servers: + - url: 'https://api.bigcommerce.com/stores/{store_hash}/v3' + variables: + store_hash: + default: store_hash + description: Permanent ID of the BigCommerce store. + description: BigCommerce API Gateway +security: + - X-Auth-Token: [] +tags: + - name: Product Modifiers + - name: Values + - name: Images +paths: + '/catalog/products/{product_id}/modifiers': + get: + tags: + - Product Modifiers + summary: Get All Product Modifiers + description: Returns a list of all *Product Modifiers*. Optional parameters can be passed in. + operationId: getModifiers + parameters: + - name: page + in: query + description: Specifies the page number in a limited (paginated) list of products. + schema: + type: integer + - name: limit + in: query + description: Controls the number of items per page in a limited (paginated) list of products. + schema: + type: integer + - name: include_fields + in: query + description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' + schema: + type: string + - name: exclude_fields + in: query + description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + title: Modifier Collection Response + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/productModifier_Full' + meta: + $ref: '#/components/schemas/metaCollection_Full' + description: Modifier Collection Response return for /GET All Modifiers. + example: + data: + - id: 206 + product_id: 158 + name: Insurance + display_name: Insurace + type: checkbox + required: true + config: + checkbox_label: $5 for insurance + checked_by_default: false + option_values: + - id: 183 + option_id: 206 + label: 'Yes' + sort_order: 0 + value_data: + checked_value: true + is_default: false + adjusters: + price: {} + weight: {} + image_url: '' + purchasing_disabled: + status: false + message: '' + - id: 184 + option_id: 206 + label: 'No' + sort_order: 1 + value_data: + checked_value: false + is_default: true + adjusters: + price: {} + weight: {} + image_url: '' + purchasing_disabled: + status: false + message: '' + meta: + pagination: + total: 1 + count: 1 + per_page: 50 + current_page: 1 + total_pages: 1 + links: + current: '?page=1&limit=50' + post: + tags: + - Product Modifiers + summary: Create a Product Modifier + description: |- + Creates a *Product Modifier*. + + **Required Fields** + * `required` + * `display_name` + * `type` + + **Read-Only Fields** + * `id` + + **Notes** + It takes two separate requests to create a new checkbox modifier with option values. Perform a request to create a modifier, then perform a second request to update option values. + operationId: createModifier + parameters: + - $ref: '#/components/parameters/ContentType' + requestBody: + content: + application/json: + schema: + title: Modifier Post + description: The model for a POST to create a modifier on a product. + allOf: + - title: Modifier Base + required: + - required + - type + type: object + properties: + type: + type: string + description: | + BigCommerce API, which determines how it will display on the storefront. Acceptable values: `date`, `checkbox`, `file`, `text`, `multi_line_text`, `numbers_only_text`, `radio_buttons`, `rectangles`, `dropdown`, `product_list`, `product_list_with_images`, `swatch`. Required in a /POST. + enum: + - date + - checkbox + - file + - text + - multi_line_text + - numbers_only_text + - radio_buttons + - rectangles + - dropdown + - product_list + - product_list_with_images + - swatch + x-required: + - post + required: + type: boolean + description: | + Whether or not this modifer is required or not at checkout. Required in a /POST. + x-required: + - post + sort_order: + type: integer + description: The order the modifiers display on the product detail page. + config: + title: Option Config + type: object + properties: + default_value: + type: string + description: | + (date, text, multi_line_text, numbers_only_text) The default value. Shown on a date option as an ISO-8601–formatted string, or on a text option as a string. + checked_by_default: + type: boolean + description: | + (checkbox) Flag for setting the checkbox to be checked by default. + checkbox_label: + type: string + description: | + (checkbox) Label displayed for the checkbox option. + date_limited: + type: boolean + description: | + (date) Flag to limit the dates allowed to be entered on a date option. + date_limit_mode: + type: string + description: | + (date) The type of limit that is allowed to be entered on a date option. + example: range + enum: + - earliest + - range + - latest + date_earliest_value: + type: string + description: | + (date) The earliest date allowed to be entered on the date option, as an ISO-8601 formatted string. + format: date-time + example: '2018-08-31T00:00:00+00:00' + date_latest_value: + type: string + description: | + (date) The latest date allowed to be entered on the date option, as an ISO-8601 formatted string. + format: date-time + example: '2019-01-01T00:00:00+00:00' + file_types_mode: + type: string + description: | + (file) The kind of restriction on the file types that can be uploaded with a file upload option. Values: `specific` - restricts uploads to particular file types; `all` - allows all file types. + example: specific + enum: + - specific + - all + file_types_supported: + type: array + description: | + (file) The type of files allowed to be uploaded if the `file_type_option` is set to `specific`. Values: + `images` - Allows upload of image MIME types (`bmp`, `gif`, `jpg`, `jpeg`, `jpe`, `jif`, `jfif`, `jfi`, `png`, `wbmp`, `xbm`, `tiff`). `documents` - Allows upload of document MIME types (`txt`, `pdf`, `rtf`, `doc`, `docx`, `xls`, `xlsx`, `accdb`, `mdb`, `one`, `pps`, `ppsx`, `ppt`, `pptx`, `pub`, `odt`, `ods`, `odp`, `odg`, `odf`). + `other` - Allows file types defined in the `file_types_other` array. + example: + - images + - documents + - other + items: + type: string + file_types_other: + type: array + description: | + (file) A list of other file types allowed with the file upload option. + example: + - pdf + - txt + items: + type: string + file_max_size: + type: integer + description: | + (file) The maximum size for a file that can be used with the file upload option. This will still be limited by the server. + example: 5 + text_characters_limited: + type: boolean + description: | + (text, multi_line_text) Flag to validate the length of a text or multi-line text input. + text_min_length: + type: integer + description: | + (text, multi_line_text) The minimum length allowed for a text or multi-line text option. + example: 1 + text_max_length: + type: integer + description: | + (text, multi_line_text) The maximum length allowed for a text or multi line text option. + example: 55 + text_lines_limited: + type: boolean + description: | + (multi_line_text) Flag to validate the maximum number of lines allowed on a multi-line text input. + example: true + text_max_lines: + type: integer + description: | + (multi_line_text) The maximum number of lines allowed on a multi-line text input. + example: 4 + number_limited: + type: boolean + description: | + (numbers_only_text) Flag to limit the value of a number option. + example: true + number_limit_mode: + type: string + description: | + (numbers_only_text) The type of limit on values entered for a number option. + example: lowest + enum: + - lowest + - highest + - range + number_lowest_value: + type: number + description: | + (numbers_only_text) The lowest allowed value for a number option if `number_limited` is true. + example: 100 + number_highest_value: + type: number + description: | + (numbers_only_text) The highest allowed value for a number option if `number_limited` is true. + number_integers_only: + type: boolean + description: | + (numbers_only_text) Flag to limit the input on a number option to whole numbers only. + example: false + product_list_adjusts_inventory: + type: boolean + description: | + (product_list, product_list_with_images) Flag for automatically adjusting inventory on a product included in the list. + product_list_adjusts_pricing: + type: boolean + description: | + (product_list, product_list_with_images) Flag to add the optional product's price to the main product's price. + product_list_shipping_calc: + type: string + description: | + (product_list, product_list_with_images) How to factor the optional product's weight and package dimensions into the shipping quote. Values: `none` - don't adjust; `weight` - use shipping weight only; `package` - use weight and dimensions. + example: weight + enum: + - none + - weight + - package + description: The values for option config can vary based on the Modifier created. + option_values: + type: array + items: + title: Modifier Value + type: object + description: 'Part of Modifier Value Response ' + allOf: + - title: Modifier Value Base + type: object + allOf: + - title: Option Value Base + required: + - label + - sort_order + type: object + properties: + is_default: + type: boolean + description: | + The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. + example: false + label: + type: string + description: | + The text display identifying the value on the storefront. Required in a /POST. + example: Green + x-required: + - post + sort_order: + maximum: 2147483647 + minimum: -2147483648 + type: integer + description: | + The order in which the value will be displayed on the product page. Required in a /POST. + example: 0 + x-required: + - post + value_data: + type: object + properties: {} + description: | + Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. + description: Common Option Value properties. + - type: object + properties: + adjusters: + type: object + properties: + price: + title: Adjuster + type: object + properties: + adjuster: + type: string + description: | + The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. + enum: + - relative + - percentage + x-nullable: true + adjuster_value: + type: number + description: | + The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. + example: 5 + description: Adjuster for Complex Rules. + weight: + title: Adjuster + type: object + properties: + adjuster: + type: string + description: | + The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. + enum: + - relative + - percentage + x-nullable: true + adjuster_value: + type: number + description: | + The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. + example: 5 + description: Adjuster for Complex Rules. + image_url: + type: string + description: | + The URL for an image displayed on the storefront when the modifier value is selected.Limit of 8MB per file. + example: 'https://cdn8.bigcommerce.com/s-{{store_hash}}/products/184/images/445/naturalcanvascart2_1024x1024__92347__29648.1534344533.1280.1280.jpg?c=2' + purchasing_disabled: + type: object + properties: + status: + type: boolean + description: | + Flag for whether the modifier value disables purchasing when selected on the storefront. This can be used for temporarily disabling a particular modifier value. + message: + type: string + description: | + The message displayed on the storefront when the purchasing disabled status is `true`. + - type: object + properties: + id: + type: integer + description: | + The unique numeric ID of the value; increments sequentially. + description: Common Modifier properties. + - required: + - display_name + type: object + properties: + display_name: + type: string + description: | + The name of the option shown on the storefront. + example: Donation + x-required: + - post + required: true + responses: + '200': + description: '' + content: + application/json: + schema: + title: Modifier Response + type: object + properties: + data: + title: Modifer + type: object + description: Product Modifier + allOf: + - title: Modifier Base + required: + - required + - type + type: object + properties: + type: + type: string + description: | + BigCommerce API, which determines how it will display on the storefront. Acceptable values: `date`, `checkbox`, `file`, `text`, `multi_line_text`, `numbers_only_text`, `radio_buttons`, `rectangles`, `dropdown`, `product_list`, `product_list_with_images`, `swatch`. Required in a /POST. + enum: + - date + - checkbox + - file + - text + - multi_line_text + - numbers_only_text + - radio_buttons + - rectangles + - dropdown + - product_list + - product_list_with_images + - swatch + x-required: + - post + required: + type: boolean + description: | + Whether or not this modifer is required or not at checkout. Required in a /POST. + x-required: + - post + sort_order: + type: integer + description: The order the modifiers display on the product detail page. + config: + title: Option Config + type: object + properties: + default_value: + type: string + description: | + (date, text, multi_line_text, numbers_only_text) The default value. Shown on a date option as an ISO-8601–formatted string, or on a text option as a string. + checked_by_default: + type: boolean + description: | + (checkbox) Flag for setting the checkbox to be checked by default. + checkbox_label: + type: string + description: | + (checkbox) Label displayed for the checkbox option. + date_limited: + type: boolean + description: | + (date) Flag to limit the dates allowed to be entered on a date option. + date_limit_mode: + type: string + description: | + (date) The type of limit that is allowed to be entered on a date option. + example: range + enum: + - earliest + - range + - latest + date_earliest_value: + type: string + description: | + (date) The earliest date allowed to be entered on the date option, as an ISO-8601 formatted string. + format: date + date_latest_value: + type: string + description: | + (date) The latest date allowed to be entered on the date option, as an ISO-8601 formatted string. + format: date + file_types_mode: + type: string + description: | + (file) The kind of restriction on the file types that can be uploaded with a file upload option. Values: `specific` - restricts uploads to particular file types; `all` - allows all file types. + example: specific + enum: + - specific + - all + file_types_supported: + type: array + description: | + (file) The type of files allowed to be uploaded if the `file_type_option` is set to `specific`. Values: + `images` - Allows upload of image MIME types (`bmp`, `gif`, `jpg`, `jpeg`, `jpe`, `jif`, `jfif`, `jfi`, `png`, `wbmp`, `xbm`, `tiff`). `documents` - Allows upload of document MIME types (`txt`, `pdf`, `rtf`, `doc`, `docx`, `xls`, `xlsx`, `accdb`, `mdb`, `one`, `pps`, `ppsx`, `ppt`, `pptx`, `pub`, `odt`, `ods`, `odp`, `odg`, `odf`). + `other` - Allows file types defined in the `file_types_other` array. + items: + type: string + example: 'images, documents, other' + file_types_other: + type: array + description: | + (file) A list of other file types allowed with the file upload option. + items: + type: string + example: pdf + file_max_size: + type: integer + description: | + (file) The maximum size for a file that can be used with the file upload option. This will still be limited by the server. + example: 5 + text_characters_limited: + type: boolean + description: | + (text, multi_line_text) Flag to validate the length of a text or multi-line text input. + text_min_length: + type: integer + description: | + (text, multi_line_text) The minimum length allowed for a text or multi-line text option. + example: 1 + text_max_length: + type: integer + description: | + (text, multi_line_text) The maximum length allowed for a text or multi line text option. + example: 55 + text_lines_limited: + type: boolean + description: | + (multi_line_text) Flag to validate the maximum number of lines allowed on a multi-line text input. + example: true + text_max_lines: + type: integer + description: | + (multi_line_text) The maximum number of lines allowed on a multi-line text input. + example: 4 + number_limited: + type: boolean + description: | + (numbers_only_text) Flag to limit the value of a number option. + example: true + number_limit_mode: + type: string + description: | + (numbers_only_text) The type of limit on values entered for a number option. + example: lowest + enum: + - lowest + - highest + - range + number_lowest_value: + type: number + description: | + (numbers_only_text) The lowest allowed value for a number option if `number_limited` is true. + example: 100 + number_highest_value: + type: number + description: | + (numbers_only_text) The highest allowed value for a number option if `number_limited` is true. + number_integers_only: + type: boolean + description: | + (numbers_only_text) Flag to limit the input on a number option to whole numbers only. + example: false + product_list_adjusts_inventory: + type: boolean + description: | + (product_list, product_list_with_images) Flag for automatically adjusting inventory on a product included in the list. + product_list_adjusts_pricing: + type: boolean + description: | + (product_list, product_list_with_images) Flag to add the optional product's price to the main product's price. + product_list_shipping_calc: + type: string + description: | + (product_list, product_list_with_images) How to factor the optional product's weight and package dimensions into the shipping quote. Values: `none` - don't adjust; `weight` - use shipping weight only; `package` - use weight and dimensions. + example: weight + enum: + - none + - weight + - package + description: The values for option config can vary based on the Modifier created. + option_values: + type: array + items: + title: Modifier Value + type: object + description: 'Part of Modifier Value Response ' + allOf: + - title: Modifier Value Base + type: object + allOf: + - title: Option Value Base + required: + - label + - sort_order + type: object + properties: + is_default: + type: boolean + description: | + The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. + example: false + label: + type: string + description: | + The text display identifying the value on the storefront. Required in a /POST. + example: Green + x-required: + - post + sort_order: + maximum: 2147483647 + minimum: -2147483648 + type: integer + description: | + The order in which the value will be displayed on the product page. Required in a /POST. + example: 0 + x-required: + - post + value_data: + type: object + properties: {} + description: | + Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. + description: Common Option Value properties. + - type: object + properties: + adjusters: + type: object + properties: + price: + title: Adjuster + type: object + properties: + adjuster: + type: string + description: | + The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. + enum: + - relative + - percentage + x-nullable: true + adjuster_value: + type: number + description: | + The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. + example: 5 + description: Adjuster for Complex Rules. + weight: + title: Adjuster + type: object + properties: + adjuster: + type: string + description: | + The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. + enum: + - relative + - percentage + x-nullable: true + adjuster_value: + type: number + description: | + The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. + example: 5 + description: Adjuster for Complex Rules. + image_url: + type: string + description: | + The URL for an image displayed on the storefront when the modifier value is selected.Limit of 8MB per file. + example: 'https://cdn8.bigcommerce.com/s-{{store_hash}}/products/184/images/445/naturalcanvascart2_1024x1024__92347__29648.1534344533.1280.1280.jpg?c=2' + purchasing_disabled: + type: object + properties: + status: + type: boolean + description: | + Flag for whether the modifier value disables purchasing when selected on the storefront. This can be used for temporarily disabling a particular modifier value. + message: + type: string + description: | + The message displayed on the storefront when the purchasing disabled status is `true`. + - type: object + properties: + id: + type: integer + description: | + The unique numeric ID of the value; increments sequentially. + description: Common Modifier properties. + - type: object + properties: + id: + type: integer + description: | + The unique numeric ID of the modifier; increments sequentially. + example: 12 + product_id: + type: integer + description: | + The unique numeric ID of the product to which the option belongs. + example: 77 + name: + type: string + description: | + The unique option name. Auto-generated from the display name, a timestamp, and the product ID. + example: Add-a-$5-Donation1535039590-191 + display_name: + type: string + description: | + The name of the option shown on the storefront. + example: Donation + meta: + $ref: '#/components/schemas/metaEmpty_Full' + '409': + description: | + The `Modifier` was in conflict with another option. This is the result of duplicate unique fields, such as `name`. + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + '422': + description: | + The `Modifier` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + x-codegen-request-body-name: Modifier + parameters: + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/ProductIdParam' + '/catalog/products/{product_id}/modifiers/{modifier_id}': + get: + tags: + - Product Modifiers + summary: Get a Modifier + description: Returns a single *Product Modifier*. Optional parameters can be passed in. + operationId: getModifierById + parameters: + - name: include_fields + in: query + description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' + schema: + type: string + - name: exclude_fields + in: query + description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + title: Modifier Response + type: object + properties: + data: + $ref: '#/components/schemas/productModifier_Full' + meta: + $ref: '#/components/schemas/metaEmpty_Full' + '404': + description: | + The resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + put: + tags: + - Product Modifiers + summary: Update a Modifier + description: Updates a *Product Modifier*. + operationId: updateModifier + parameters: + - $ref: '#/components/parameters/ContentType' + requestBody: + content: + application/json: + schema: + title: Modifier Put + description: The model for a PUT to update a modifier on a product. + allOf: + - title: Modifier Base + required: + - required + - type + type: object + properties: + type: + type: string + description: | + BigCommerce API, which determines how it will display on the storefront. Acceptable values: `date`, `checkbox`, `file`, `text`, `multi_line_text`, `numbers_only_text`, `radio_buttons`, `rectangles`, `dropdown`, `product_list`, `product_list_with_images`, `swatch`. Required in a /POST. + enum: + - date + - checkbox + - file + - text + - multi_line_text + - numbers_only_text + - radio_buttons + - rectangles + - dropdown + - product_list + - product_list_with_images + - swatch + x-required: + - post + required: + type: boolean + description: | + Whether or not this modifier is required or not at checkout. Required in a /POST. + x-required: + - post + sort_order: + type: integer + description: The order the modifiers display on the product detail page. + config: + title: Option Config + type: object + properties: + default_value: + type: string + description: | + (date, text, multi_line_text, numbers_only_text) The default value. Shown on a date option as an ISO-8601–formatted string, or on a text option as a string. + checked_by_default: + type: boolean + description: | + (checkbox) Flag for setting the checkbox to be checked by default. + checkbox_label: + type: string + description: | + (checkbox) Label displayed for the checkbox option. + date_limited: + type: boolean + description: | + (date) Flag to limit the dates allowed to be entered on a date option. + date_limit_mode: + type: string + description: | + (date) The type of limit that is allowed to be entered on a date option. + example: range + enum: + - earliest + - range + - latest + date_earliest_value: + type: string + description: | + (date) The earliest date allowed to be entered on the date option, as an ISO-8601 formatted string. + format: date + date_latest_value: + type: string + description: | + (date) The latest date allowed to be entered on the date option, as an ISO-8601 formatted string. + format: date + file_types_mode: + type: string + description: | + (file) The kind of restriction on the file types that can be uploaded with a file upload option. Values: `specific` - restricts uploads to particular file types; `all` - allows all file types. + example: specific + enum: + - specific + - all + file_types_supported: + type: array + description: | + (file) The type of files allowed to be uploaded if the `file_type_option` is set to `specific`. Values: + `images` - Allows upload of image MIME types (`bmp`, `gif`, `jpg`, `jpeg`, `jpe`, `jif`, `jfif`, `jfi`, `png`, `wbmp`, `xbm`, `tiff`). `documents` - Allows upload of document MIME types (`txt`, `pdf`, `rtf`, `doc`, `docx`, `xls`, `xlsx`, `accdb`, `mdb`, `one`, `pps`, `ppsx`, `ppt`, `pptx`, `pub`, `odt`, `ods`, `odp`, `odg`, `odf`). + `other` - Allows file types defined in the `file_types_other` array. + items: + type: string + example: 'images, documents, other' + file_types_other: + type: array + description: | + (file) A list of other file types allowed with the file upload option. + items: + type: string + example: pdf + file_max_size: + type: integer + description: | + (file) The maximum size for a file that can be used with the file upload option. This will still be limited by the server. + example: 5 + text_characters_limited: + type: boolean + description: | + (text, multi_line_text) Flag to validate the length of a text or multi-line text input. + text_min_length: + type: integer + description: | + (text, multi_line_text) The minimum length allowed for a text or multi-line text option. + example: 1 + text_max_length: + type: integer + description: | + (text, multi_line_text) The maximum length allowed for a text or multi line text option. + example: 55 + text_lines_limited: + type: boolean + description: | + (multi_line_text) Flag to validate the maximum number of lines allowed on a multi-line text input. + example: true + text_max_lines: + type: integer + description: | + (multi_line_text) The maximum number of lines allowed on a multi-line text input. + example: 4 + number_limited: + type: boolean + description: | + (numbers_only_text) Flag to limit the value of a number option. + example: true + number_limit_mode: + type: string + description: | + (numbers_only_text) The type of limit on values entered for a number option. + example: lowest + enum: + - lowest + - highest + - range + number_lowest_value: + type: number + description: | + (numbers_only_text) The lowest allowed value for a number option if `number_limited` is true. + example: 100 + number_highest_value: + type: number + description: | + (numbers_only_text) The highest allowed value for a number option if `number_limited` is true. + number_integers_only: + type: boolean + description: | + (numbers_only_text) Flag to limit the input on a number option to whole numbers only. + example: false + product_list_adjusts_inventory: + type: boolean + description: | + (product_list, product_list_with_images) Flag for automatically adjusting inventory on a product included in the list. + product_list_adjusts_pricing: + type: boolean + description: | + (product_list, product_list_with_images) Flag to add the optional product's price to the main product's price. + product_list_shipping_calc: + type: string + description: | + (product_list, product_list_with_images) How to factor the optional product's weight and package dimensions into the shipping quote. Values: `none` - don't adjust; `weight` - use shipping weight only; `package` - use weight and dimensions. + example: weight + enum: + - none + - weight + - package + description: The values for option config can vary based on the Modifier created. + option_values: + type: array + items: + title: Modifier Value + type: object + properties: + id: + type: integer + description: | + The unique numeric ID of the value; increments sequentially. + description: 'Part of Modifier Value Response ' + display_name: + type: string + description: | + The name of the option shown on the storefront. + example: Donation + description: Common Modifier properties. + required: true + responses: + '200': + description: '' + content: + application/json: + schema: + title: Modifier Response + type: object + properties: + data: + title: Modifer + type: object + description: Product Modifier + allOf: + - title: Modifier Base + required: + - required + - type + type: object + properties: + type: + type: string + description: | + BigCommerce API, which determines how it will display on the storefront. Acceptable values: `date`, `checkbox`, `file`, `text`, `multi_line_text`, `numbers_only_text`, `radio_buttons`, `rectangles`, `dropdown`, `product_list`, `product_list_with_images`, `swatch`. Required in a /POST. + enum: + - date + - checkbox + - file + - text + - multi_line_text + - numbers_only_text + - radio_buttons + - rectangles + - dropdown + - product_list + - product_list_with_images + - swatch + x-required: + - post + required: + type: boolean + description: | + Whether or not this modifer is required or not at checkout. Required in a /POST. + x-required: + - post + sort_order: + type: integer + description: The order the modifiers display on the product detail page. + config: + title: Option Config + type: object + properties: + default_value: + type: string + description: | + (date, text, multi_line_text, numbers_only_text) The default value. Shown on a date option as an ISO-8601–formatted string, or on a text option as a string. + checked_by_default: + type: boolean + description: | + (checkbox) Flag for setting the checkbox to be checked by default. + checkbox_label: + type: string + description: | + (checkbox) Label displayed for the checkbox option. + date_limited: + type: boolean + description: | + (date) Flag to limit the dates allowed to be entered on a date option. + date_limit_mode: + type: string + description: | + (date) The type of limit that is allowed to be entered on a date option. + example: range + enum: + - earliest + - range + - latest + date_earliest_value: + type: string + description: | + (date) The earliest date allowed to be entered on the date option, as an ISO-8601 formatted string. + format: date + date_latest_value: + type: string + description: | + (date) The latest date allowed to be entered on the date option, as an ISO-8601 formatted string. + format: date + file_types_mode: + type: string + description: | + (file) The kind of restriction on the file types that can be uploaded with a file upload option. Values: `specific` - restricts uploads to particular file types; `all` - allows all file types. + example: specific + enum: + - specific + - all + file_types_supported: + type: array + description: | + (file) The type of files allowed to be uploaded if the `file_type_option` is set to `specific`. Values: + `images` - Allows upload of image MIME types (`bmp`, `gif`, `jpg`, `jpeg`, `jpe`, `jif`, `jfif`, `jfi`, `png`, `wbmp`, `xbm`, `tiff`). `documents` - Allows upload of document MIME types (`txt`, `pdf`, `rtf`, `doc`, `docx`, `xls`, `xlsx`, `accdb`, `mdb`, `one`, `pps`, `ppsx`, `ppt`, `pptx`, `pub`, `odt`, `ods`, `odp`, `odg`, `odf`). + `other` - Allows file types defined in the `file_types_other` array. + items: + type: string + example: 'images, documents, other' + file_types_other: + type: array + description: | + (file) A list of other file types allowed with the file upload option. + items: + type: string + example: pdf + file_max_size: + type: integer + description: | + (file) The maximum size for a file that can be used with the file upload option. This will still be limited by the server. + example: 5 + text_characters_limited: + type: boolean + description: | + (text, multi_line_text) Flag to validate the length of a text or multi-line text input. + text_min_length: + type: integer + description: | + (text, multi_line_text) The minimum length allowed for a text or multi-line text option. + example: 1 + text_max_length: + type: integer + description: | + (text, multi_line_text) The maximum length allowed for a text or multi line text option. + example: 55 + text_lines_limited: + type: boolean + description: | + (multi_line_text) Flag to validate the maximum number of lines allowed on a multi-line text input. + example: true + text_max_lines: + type: integer + description: | + (multi_line_text) The maximum number of lines allowed on a multi-line text input. + example: 4 + number_limited: + type: boolean + description: | + (numbers_only_text) Flag to limit the value of a number option. + example: true + number_limit_mode: + type: string + description: | + (numbers_only_text) The type of limit on values entered for a number option. + example: lowest + enum: + - lowest + - highest + - range + number_lowest_value: + type: number + description: | + (numbers_only_text) The lowest allowed value for a number option if `number_limited` is true. + example: 100 + number_highest_value: + type: number + description: | + (numbers_only_text) The highest allowed value for a number option if `number_limited` is true. + number_integers_only: + type: boolean + description: | + (numbers_only_text) Flag to limit the input on a number option to whole numbers only. + example: false + product_list_adjusts_inventory: + type: boolean + description: | + (product_list, product_list_with_images) Flag for automatically adjusting inventory on a product included in the list. + product_list_adjusts_pricing: + type: boolean + description: | + (product_list, product_list_with_images) Flag to add the optional product's price to the main product's price. + product_list_shipping_calc: + type: string + description: | + (product_list, product_list_with_images) How to factor the optional product's weight and package dimensions into the shipping quote. Values: `none` - don't adjust; `weight` - use shipping weight only; `package` - use weight and dimensions. + example: weight + enum: + - none + - weight + - package + description: The values for option config can vary based on the Modifier created. + option_values: + type: array + items: + title: Modifier Value + type: object + description: 'Part of Modifier Value Response ' + allOf: + - title: Modifier Value Base + type: object + allOf: + - title: Option Value Base + required: + - label + - sort_order + type: object + properties: + is_default: + type: boolean + description: | + The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. + example: false + label: + type: string + description: | + The text display identifying the value on the storefront. Required in a /POST. + example: Green + x-required: + - post + sort_order: + maximum: 2147483647 + minimum: -2147483648 + type: integer + description: | + The order in which the value will be displayed on the product page. Required in a /POST. + example: 0 + x-required: + - post + value_data: + type: object + properties: {} + description: | + Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. + description: Common Option Value properties. + - type: object + properties: + adjusters: + type: object + properties: + price: + title: Adjuster + type: object + properties: + adjuster: + type: string + description: | + The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. + enum: + - relative + - percentage + x-nullable: true + adjuster_value: + type: number + description: | + The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. + example: 5 + description: Adjuster for Complex Rules. + weight: + title: Adjuster + type: object + properties: + adjuster: + type: string + description: | + The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. + enum: + - relative + - percentage + x-nullable: true + adjuster_value: + type: number + description: | + The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. + example: 5 + description: Adjuster for Complex Rules. + image_url: + type: string + description: | + The URL for an image displayed on the storefront when the modifier value is selected.Limit of 8MB per file. + example: 'https://cdn8.bigcommerce.com/s-{{store_hash}}/products/184/images/445/naturalcanvascart2_1024x1024__92347__29648.1534344533.1280.1280.jpg?c=2' + purchasing_disabled: + type: object + properties: + status: + type: boolean + description: | + Flag for whether the modifier value disables purchasing when selected on the storefront. This can be used for temporarily disabling a particular modifier value. + message: + type: string + description: | + The message displayed on the storefront when the purchasing disabled status is `true`. + - type: object + properties: + id: + type: integer + description: | + The unique numeric ID of the value; increments sequentially. + description: Common Modifier properties. + - type: object + properties: + id: + type: integer + description: | + The unique numeric ID of the modifier; increments sequentially. + example: 12 + product_id: + type: integer + description: | + The unique numeric ID of the product to which the option belongs. + example: 77 + name: + type: string + description: | + The unique option name. Auto-generated from the display name, a timestamp, and the product ID. + example: Add-a-$5-Donation1535039590-191 + display_name: + type: string + description: | + The name of the option shown on the storefront. + example: Donation + meta: + $ref: '#/components/schemas/metaEmpty_Full' + '409': + description: | + The `Modifier` was in conflict with another modifier or option. This is the result of duplicate unique fields, such as `name`. + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + '422': + description: | + The `Modifier` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + x-codegen-request-body-name: Modifier + delete: + tags: + - Product Modifiers + summary: Delete a Modifier + description: Deletes a *Product Modifier*. + operationId: deleteModifierById + responses: + '204': + description: '' + content: {} + parameters: + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/ProductIdParam' + - $ref: '#/components/parameters/ModifierIdParam' + '/catalog/products/{product_id}/modifiers/{modifier_id}/values': + get: + tags: + - Values + summary: Get All Modifier Values + description: Returns a list of all product *Modifier Values*. Optional parameters can be passed in. + operationId: getModifierValues + parameters: + - name: modifier_id + in: path + description: | + The ID of the `Modifier`. + required: true + schema: + type: integer + + - name: include_fields + in: query + description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' + schema: + type: string + - name: exclude_fields + in: query + description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' + schema: + type: string + - name: page + in: query + description: Specifies the page number in a limited (paginated) list of products. + schema: + type: integer + - name: limit + in: query + description: Controls the number of items per page in a limited (paginated) list of products. + schema: + type: integer + responses: + '200': + description: '' + content: + application/json: + schema: + title: Modifier Value Collection Response + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/productModifierOptionValue_Full' + meta: + $ref: '#/components/schemas/metaCollection_Full' + description: Returns for GET All Modifier Values on a Product + example: + data: + - id: 190 + option_id: 222 + label: 'Yes' + sort_order: 0 + value_data: + checked_value: true + is_default: false + adjusters: + price: + adjuster: relative + adjuster_value: 5 + weight: {} + image_url: '' + purchasing_disabled: + status: false + message: '' + - id: 191 + option_id: 222 + label: 'No' + sort_order: 1 + value_data: + checked_value: false + is_default: true + adjusters: + price: {} + weight: {} + image_url: '' + purchasing_disabled: + status: false + message: '' + meta: + pagination: + total: 2 + count: 2 + per_page: 50 + current_page: 1 + total_pages: 1 + links: + current: '?page=1&limit=50' + post: + tags: + - Values + summary: Create Modifier Value + description: |- + Creates a *Modifier Value*. + + **Required Fields** + * label + * sort_order + + **Read-Only Fields** + * id + operationId: createModifierValue + parameters: + - $ref: '#/components/parameters/ContentType' + - name: modifier_id + in: path + description: | + The ID of the `Modifier`. + required: true + schema: + type: integer + requestBody: + content: + application/json: + schema: + title: Modifier Value Post + description: The model for a POST to create a modifier value on a product. + allOf: + - title: Modifier Value Base + allOf: + - title: Option Value Base + required: + - label + - sort_order + type: object + properties: + is_default: + type: boolean + description: | + The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. + example: false + label: + type: string + description: | + The text display identifying the value on the storefront. Required in a /POST. + example: Green + x-required: + - post + sort_order: + maximum: 2147483647 + minimum: -2147483648 + type: integer + description: | + The order in which the value will be displayed on the product page. Required in a /POST. + example: 0 + x-required: + - post + value_data: + type: object + properties: {} + description: | + Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. + description: Common Option Value properties. + - type: object + properties: + adjusters: + type: object + properties: + price: + title: Adjuster + type: object + properties: + adjuster: + type: string + description: | + The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. + nullable: true + enum: + - relative + - percentage + adjuster_value: + type: number + description: | + The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. + example: 5 + description: Adjuster for Complex Rules. + weight: + title: Adjuster + type: object + properties: + adjuster: + type: string + description: | + The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. + nullable: true + enum: + - relative + - percentage + adjuster_value: + type: number + description: | + The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. + example: 5 + description: Adjuster for Complex Rules. + image_url: + type: string + description: | + The URL for an image displayed on the storefront when the modifier value is selected.Limit of 8MB per file. + example: 'https://cdn8.bigcommerce.com/s-{{store_hash}}/products/184/images/445/naturalcanvascart2_1024x1024__92347__29648.1534344533.1280.1280.jpg?c=2' + purchasing_disabled: + type: object + properties: + status: + type: boolean + description: | + Flag for whether the modifier value disables purchasing when selected on the storefront. This can be used for temporarily disabling a particular modifier value. + message: + type: string + description: | + The message displayed on the storefront when the purchasing disabled status is `true`. + required: true + responses: + '200': + description: '' + content: + application/json: + schema: + title: Modifier Value Response + type: object + properties: + data: + title: Modifier Value + type: object + description: 'Part of Modifier Value Response ' + allOf: + - title: Modifier Value Base + type: object + allOf: + - title: Option Value Base + required: + - label + - sort_order + type: object + properties: + is_default: + type: boolean + description: | + The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. + example: false + label: + type: string + description: | + The text display identifying the value on the storefront. Required in a /POST. + example: Green + x-required: + - post + sort_order: + maximum: 2147483647 + minimum: -2147483648 + type: integer + description: | + The order in which the value will be displayed on the product page. Required in a /POST. + example: 0 + x-required: + - post + value_data: + type: object + properties: {} + description: | + Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. + description: Common Option Value properties. + - type: object + properties: + adjusters: + type: object + properties: + price: + title: Adjuster + type: object + properties: + adjuster: + type: string + description: | + The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. + enum: + - relative + - percentage + x-nullable: true + adjuster_value: + type: number + description: | + The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. + example: 5 + description: Adjuster for Complex Rules. + weight: + title: Adjuster + type: object + properties: + adjuster: + type: string + description: | + The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. + enum: + - relative + - percentage + x-nullable: true + adjuster_value: + type: number + description: | + The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. + example: 5 + description: Adjuster for Complex Rules. + image_url: + type: string + description: | + The URL for an image displayed on the storefront when the modifier value is selected.Limit of 8MB per file. + example: 'https://cdn8.bigcommerce.com/s-{{store_hash}}/products/184/images/445/naturalcanvascart2_1024x1024__92347__29648.1534344533.1280.1280.jpg?c=2' + purchasing_disabled: + type: object + properties: + status: + type: boolean + description: | + Flag for whether the modifier value disables purchasing when selected on the storefront. This can be used for temporarily disabling a particular modifier value. + message: + type: string + description: | + The message displayed on the storefront when the purchasing disabled status is `true`. + - type: object + properties: + id: + type: integer + description: | + The unique numeric ID of the value; increments sequentially. + meta: + $ref: '#/components/schemas/metaEmpty_Full' + example: + data: + id: 190 + option_id: 222 + label: 'Yes' + sort_order: 0 + value_data: {} + is_default: false + adjusters: + price: + adjuster: relative + adjuster_value: 5 + weight: {} + image_url: '' + purchasing_disabled: + status: false + message: '' + meta: {} + '422': + description: | + The `ModifierValue` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + x-codegen-request-body-name: ModifierValue + parameters: + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/ProductIdParam' + - $ref: '#/components/parameters/ModifierIdParam' + '/catalog/products/{product_id}/modifiers/{modifier_id}/values/{value_id}': + get: + tags: + - Values + summary: Get a Modifier Value + description: Returns a single *Modifier Value*. Optional parameters can be passed in. + operationId: getModifierValueById + parameters: + - name: modifier_id + in: path + description: | + The ID of the `Modifier`. + required: true + schema: + type: integer + - name: value_id + in: path + description: | + The ID of the `Modifier/Option Value`. + required: true + schema: + type: integer + + - name: include_fields + in: query + description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' + schema: + type: string + - name: exclude_fields + in: query + description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + title: Modifier Value Response + type: object + properties: + data: + $ref: '#/components/schemas/productModifierOptionValue_Full' + meta: + $ref: '#/components/schemas/metaEmpty_Full' + example: + data: + id: 190 + option_id: 222 + label: 'Yes' + sort_order: 0 + value_data: {} + is_default: false + adjusters: + price: + adjuster: relative + adjuster_value: 5 + weight: {} + image_url: '' + purchasing_disabled: + status: false + message: '' + meta: {} + '404': + description: | + The resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + security: + - X-Auth-Token: [] + put: + tags: + - Values + summary: Update a Modifier Value + description: |- + Updates a *Modifier Value*. + + **Required Fields** + * none + + **Read-Only Fields** + * id + operationId: updateModifierValue + parameters: + - $ref: '#/components/parameters/ContentType' + - name: modifier_id + in: path + description: | + The ID of the `Modifier`. + required: true + schema: + type: integer + - name: value_id + in: path + description: | + The ID of the `Modifier/Option Value`. + required: true + schema: + type: integer + requestBody: + content: + application/json: + schema: + title: Modifier Value Put + description: The model for a PUT to update a modifier value on a product. + allOf: + - title: Modifier Value Base + allOf: + - title: Option Value Base + required: + - label + - sort_order + type: object + properties: + is_default: + type: boolean + description: | + The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. + example: false + label: + type: string + description: | + The text display identifying the value on the storefront. Required in a /POST. + example: Green + x-required: + - post + sort_order: + maximum: 2147483647 + minimum: -2147483648 + type: integer + description: | + The order in which the value will be displayed on the product page. Required in a /POST. + example: 0 + x-required: + - post + value_data: + type: object + properties: {} + description: | + Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. + description: Common Option Value properties. + - type: object + properties: + adjusters: + type: object + properties: + price: + title: Adjuster + type: object + properties: + adjuster: + type: string + description: | + The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. + nullable: true + enum: + - relative + - percentage + adjuster_value: + type: number + description: | + The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. + example: 5 + description: Adjuster for Complex Rules. + weight: + title: Adjuster + type: object + properties: + adjuster: + type: string + description: | + The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. + nullable: true + enum: + - relative + - percentage + adjuster_value: + type: number + description: | + The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. + example: 5 + description: Adjuster for Complex Rules. + image_url: + type: string + description: | + The URL for an image displayed on the storefront when the modifier value is selected.Limit of 8MB per file. + example: 'https://cdn8.bigcommerce.com/s-{{store_hash}}/products/184/images/445/naturalcanvascart2_1024x1024__92347__29648.1534344533.1280.1280.jpg?c=2' + purchasing_disabled: + type: object + properties: + status: + type: boolean + description: | + Flag for whether the modifier value disables purchasing when selected on the storefront. This can be used for temporarily disabling a particular modifier value. + message: + type: string + description: | + The message displayed on the storefront when the purchasing disabled status is `true`. + - type: object + properties: + id: + type: integer + description: | + The unique numeric ID of the value; increments sequentially. + x-required: + - put + required: true + responses: + '200': + description: '' + content: + application/json: + schema: + title: Modifier Value Response + type: object + properties: + data: + title: Modifier Value + type: object + description: 'Part of Modifier Value Response ' + allOf: + - title: Modifier Value Base + type: object + allOf: + - title: Option Value Base + required: + - label + - sort_order + type: object + properties: + is_default: + type: boolean + description: | + The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. + example: false + label: + type: string + description: | + The text display identifying the value on the storefront. Required in a /POST. + example: Green + x-required: + - post + sort_order: + maximum: 2147483647 + minimum: -2147483648 + type: integer + description: | + The order in which the value will be displayed on the product page. Required in a /POST. + example: 0 + x-required: + - post + value_data: + type: object + properties: {} + description: | + Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. + description: Common Option Value properties. + - type: object + properties: + adjusters: + type: object + properties: + price: + title: Adjuster + type: object + properties: + adjuster: + type: string + description: | + The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. + enum: + - relative + - percentage + x-nullable: true + adjuster_value: + type: number + description: | + The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. + example: 5 + description: Adjuster for Complex Rules. + weight: + title: Adjuster + type: object + properties: + adjuster: + type: string + description: | + The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. + enum: + - relative + - percentage + x-nullable: true + adjuster_value: + type: number + description: | + The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. + example: 5 + description: Adjuster for Complex Rules. + image_url: + type: string + description: | + The URL for an image displayed on the storefront when the modifier value is selected.Limit of 8MB per file. + example: 'https://cdn8.bigcommerce.com/s-{{store_hash}}/products/184/images/445/naturalcanvascart2_1024x1024__92347__29648.1534344533.1280.1280.jpg?c=2' + purchasing_disabled: + type: object + properties: + status: + type: boolean + description: | + Flag for whether the modifier value disables purchasing when selected on the storefront. This can be used for temporarily disabling a particular modifier value. + message: + type: string + description: | + The message displayed on the storefront when the purchasing disabled status is `true`. + - type: object + properties: + id: + type: integer + description: | + The unique numeric ID of the value; increments sequentially. + meta: + $ref: '#/components/schemas/metaEmpty_Full' + example: + data: + id: 190 + option_id: 222 + label: 'Yes' + sort_order: 0 + value_data: {} + is_default: false + adjusters: + price: + adjuster: relative + adjuster_value: 5 + weight: {} + image_url: '' + purchasing_disabled: + status: false + message: '' + meta: {} + '422': + description: | + The `ModifierValue` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + x-codegen-request-body-name: ModifierValue + delete: + tags: + - Values + summary: Delete Modifier Value + description: Deletes a *Modifier Value*. + operationId: deleteModifierValueById + parameters: + - name: modifier_id + in: path + description: | + The ID of the `Modifier`. + required: true + schema: + type: integer + - name: value_id + in: path + description: | + The ID of the `Modifier/Option Value`. + required: true + schema: + type: integer + responses: + '204': + description: '' + content: {} + parameters: + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/ProductIdParam' + - $ref: '#/components/parameters/ModifierIdParam' + - $ref: '#/components/parameters/ValueIdParam' + '/catalog/products/{product_id}/modifiers/{modifier_id}/values/{value_id}/image': + post: + tags: + - Images + summary: Create Modifier Image + description: |- + Creates a *Modifier Image*. + + The image will show on the storefront when the value is selected. + + **Required Fields** + - image_file: Form posts are the only accepted upload option. + operationId: createModifierImage + parameters: + - $ref: '#/components/parameters/ContentType' + - name: modifier_id + in: path + description: | + The ID of the `Modifier`. + required: true + schema: + type: integer + - name: value_id + in: path + description: | + The ID of the `Modifier`. + required: true + schema: + type: integer + requestBody: + content: + multipart/form-data: + schema: + type: object + properties: + image_file: + type: string + format: binary + responses: + '200': + description: '' + content: + application/json: + schema: + title: Image Response + type: object + properties: + data: + title: Resource Image + type: object + properties: + image_url: + type: string + description: | + A public URL for a GIF, JPEG, or PNG image. Limit of 8MB per file. + description: 'An object containing a publicly accessible image URL, or a form post that contains an image file.' + meta: + $ref: '#/components/schemas/metaEmpty_Full' + description: |- + Image Response returns for: + * Create Variant Image + * Create Modifier Image + * Create Category Image + * Create Brand Image + example: + data: + image_url: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/product_images/attribute_rule_images/85_source_1536863430.png' + meta: {} + '400': + description: Bad Request. The requested resource could not be downloaded and may be invalid. Possible reasons include malformed request syntax or the file host blocking requests. + content: + application/json: + schema: + type: object + properties: {} + '404': + description: | + The resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + '422': + description: | + Modifier image was not valid. This is the result of missing `image_file` fields, or of a non-URL value for the `image_file` field. See the response for more details. + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + parameters: + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/ProductIdParam' + - $ref: '#/components/parameters/ModifierIdParam' + - $ref: '#/components/parameters/ValueIdParam' +components: + schemas: + productModifier_Base: + title: productModifier_Base + required: + - required + - type + type: object + properties: + type: + type: string + description: | + BigCommerce API, which determines how it will display on the storefront. Acceptable values: `date`, `checkbox`, `file`, `text`, `multi_line_text`, `numbers_only_text`, `radio_buttons`, `rectangles`, `dropdown`, `product_list`, `product_list_with_images`, `swatch`. Required in a /POST. + enum: + - date + - checkbox + - file + - text + - multi_line_text + - numbers_only_text + - radio_buttons + - rectangles + - dropdown + - product_list + - product_list_with_images + - swatch + x-required: + - post + required: + type: boolean + description: | + Whether or not this modifer is required or not at checkout. Required in a /POST. + x-required: + - post + sort_order: + type: integer + description: The order the modifiers display on the product detail page. + config: + $ref: '#/components/schemas/config_Full' + display_name: + type: string + description: The name of the option shown on the storefront. + description: Common Modifier properties. + x-internal: false + productModifier_Full: + title: productModifier_Full + description: Product Modifier + allOf: + - $ref: '#/components/schemas/productModifier_Base' + - type: object + properties: + id: + type: integer + description: | + The unique numeric ID of the modifier; increments sequentially. + example: 12 + product_id: + type: integer + description: | + The unique numeric ID of the product to which the option belongs. + example: 77 + name: + type: string + description: | + The unique option name. Auto-generated from the display name, a timestamp, and the product ID. + example: Add-a-$5-Donation1535039590-191 + option_values: + type: array + items: + $ref: '#/components/schemas/productModifierOptionValue_Full' + x-internal: false + productModifierOptionValue_Base: + title: productModifierOptionValue_Base + required: + - label + - sort_order + type: object + properties: + is_default: + type: boolean + description: | + The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. + example: false + label: + type: string + description: | + The text display identifying the value on the storefront. Required in a /POST. + example: Green + x-required: + - post + sort_order: + maximum: 2147483647 + minimum: -2147483648 + type: integer + description: | + The order in which the value will be displayed on the product page. Required in a /POST. + example: 0 + x-required: + - post + value_data: + type: object + properties: {} + description: | + Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. If no data is available, returns `null`. + nullable: true + adjusters: + $ref: '#/components/schemas/adjusters_Full' + description: Common Product Modifer `option_value` properties. + x-internal: false + productModifierOptionValue_Full: + title: productModifierOptionValue_Full + description: Product Modifer `option_value`. + allOf: + - $ref: '#/components/schemas/productModifierOptionValue_Base' + - type: object + properties: + id: + type: integer + description: | + The unique numeric ID of the value; increments sequentially. + option_id: + type: integer + x-internal: false + adjuster_Full: + title: adjuster_Full + type: object + properties: + adjuster: + type: string + description: | + The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. + nullable: true + enum: + - relative + - percentage + adjuster_value: + type: number + description: | + The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. + example: 5 + description: Adjuster for Complex Rules. + x-internal: false + metaCollection_Full: + title: metaCollection_Full + type: object + properties: + pagination: + $ref: '#/components/schemas/pagination_Full' + description: 'Data about the response, including pagination and collection totals.' + x-internal: false + pagination_Full: + title: pagination_Full + type: object + properties: + total: + type: integer + description: | + Total number of items in the result set. + example: 36 + count: + type: integer + description: | + Total number of items in the collection response. + example: 36 + per_page: + type: integer + description: | + The amount of items returned in the collection per page, controlled by the limit parameter. + example: 50 + current_page: + type: integer + description: | + The page you are currently on within the collection. + example: 1 + total_pages: + type: integer + description: | + The total number of pages in the collection. + example: 1 + links: + type: object + properties: + previous: + type: string + description: | + Link to the previous page returned in the response. + current: + type: string + description: | + Link to the current page returned in the response. + example: '?page=1&limit=50' + next: + type: string + description: | + Link to the next page returned in the response. + description: | + Pagination links for the previous and next parts of the whole collection. + description: 'Data about the response, including pagination and collection totals.' + x-internal: false + metaEmpty_Full: + type: object + title: Response meta + properties: {} + additionalProperties: true + description: Response metadata. + config_Full: + title: config_Full + type: object + properties: + default_value: + type: string + description: | + (date, text, multi_line_text, numbers_only_text) The default value. Shown on a date option as an ISO-8601–formatted string, or on a text option as a string. + checked_by_default: + type: boolean + description: | + (checkbox) Flag for setting the checkbox to be checked by default. + checkbox_label: + type: string + description: | + (checkbox) Label displayed for the checkbox option. + date_limited: + type: boolean + description: | + (date) Flag to limit the dates allowed to be entered on a date option. + date_limit_mode: + type: string + description: | + (date) The type of limit that is allowed to be entered on a date option. + example: range + enum: + - earliest + - range + - latest + date_earliest_value: + type: string + description: | + (date) The earliest date allowed to be entered on the date option, as an ISO-8601 formatted string. + format: date + date_latest_value: + type: string + description: | + (date) The latest date allowed to be entered on the date option, as an ISO-8601 formatted string. + format: date + file_types_mode: + type: string + description: | + (file) The kind of restriction on the file types that can be uploaded with a file upload option. Values: `specific` - restricts uploads to particular file types; `all` - allows all file types. + example: specific + enum: + - specific + - all + file_types_supported: + type: array + description: | + (file) The type of files allowed to be uploaded if the `file_type_option` is set to `specific`. Values: + `images` - Allows upload of image MIME types (`bmp`, `gif`, `jpg`, `jpeg`, `jpe`, `jif`, `jfif`, `jfi`, `png`, `wbmp`, `xbm`, `tiff`). `documents` - Allows upload of document MIME types (`txt`, `pdf`, `rtf`, `doc`, `docx`, `xls`, `xlsx`, `accdb`, `mdb`, `one`, `pps`, `ppsx`, `ppt`, `pptx`, `pub`, `odt`, `ods`, `odp`, `odg`, `odf`). + `other` - Allows file types defined in the `file_types_other` array. + items: + type: string + example: 'images, documents, other' + file_types_other: + type: array + description: | + (file) A list of other file types allowed with the file upload option. + items: + type: string + example: pdf + file_max_size: + type: integer + description: | + (file) The maximum size for a file that can be used with the file upload option. This will still be limited by the server. + example: 5 + text_characters_limited: + type: boolean + description: | + (text, multi_line_text) Flag to validate the length of a text or multi-line text input. + text_min_length: + type: integer + description: | + (text, multi_line_text) The minimum length allowed for a text or multi-line text option. + example: 1 + text_max_length: + type: integer + description: | + (text, multi_line_text) The maximum length allowed for a text or multi line text option. + example: 55 + text_lines_limited: + type: boolean + description: | + (multi_line_text) Flag to validate the maximum number of lines allowed on a multi-line text input. + example: true + text_max_lines: + type: integer + description: | + (multi_line_text) The maximum number of lines allowed on a multi-line text input. + example: 4 + number_limited: + type: boolean + description: | + (numbers_only_text) Flag to limit the value of a number option. + example: true + number_limit_mode: + type: string + description: | + (numbers_only_text) The type of limit on values entered for a number option. + example: lowest + enum: + - lowest + - highest + - range + number_lowest_value: + type: number + description: | + (numbers_only_text) The lowest allowed value for a number option if `number_limited` is true. + example: 100 + number_highest_value: + type: number + description: | + (numbers_only_text) The highest allowed value for a number option if `number_limited` is true. + number_integers_only: + type: boolean + description: | + (numbers_only_text) Flag to limit the input on a number option to whole numbers only. + example: false + product_list_adjusts_inventory: + type: boolean + description: | + (product_list, product_list_with_images) Flag for automatically adjusting inventory on a product included in the list. + product_list_adjusts_pricing: + type: boolean + description: | + (product_list, product_list_with_images) Flag to add the optional product's price to the main product's price. + product_list_shipping_calc: + type: string + description: | + (product_list, product_list_with_images) How to factor the optional product's weight and package dimensions into the shipping quote. Values: `none` - don't adjust; `weight` - use shipping weight only; `package` - use weight and dimensions. + example: weight + enum: + - none + - weight + - package + description: The values for option config can vary based on the Modifier created. + x-internal: false + adjusters_Full: + title: adjusters_Full + type: object + properties: + price: + $ref: '#/components/schemas/adjuster_Full' + weight: + $ref: '#/components/schemas/adjuster_Full' + image_url: + type: string + description: | + The URL for an image displayed on the storefront when the modifier value is selected.Limit of 8MB per file. + example: 'https://cdn8.bigcommerce.com/s-{{store_hash}}/products/184/images/445/naturalcanvascart2_1024x1024__92347__29648.1534344533.1280.1280.jpg?c=2' + purchasing_disabled: + type: object + properties: + status: + type: boolean + description: | + Flag for whether the modifier value disables purchasing when selected on the storefront. This can be used for temporarily disabling a particular modifier value. + message: + type: string + description: | + The message displayed on the storefront when the purchasing disabled status is `true`. + x-internal: false + parameters: + ProductIdParam: + name: product_id + in: path + description: | + The ID of the `Product` to which the resource belongs. + required: true + schema: + type: integer + ModifierIdParam: + name: modifier_id + description: | + The ID of the `Modifier`. + required: true + in: path + schema: + type: integer + ValueIdParam: + name: value_id + description: | + The ID of the `Modifier/Option Value`. + required: true + in: path + schema: + type: integer + Accept: + name: Accept + in: header + required: true + description: 'The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body.' + schema: + type: string + default: 'application/json' + ContentType: + name: Content-Type + in: header + required: true + description: 'The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the request body.' + schema: + type: string + default: 'application/json' + securitySchemes: + X-Auth-Token: + name: X-Auth-Token + description: |- + ### OAuth scopes + + | UI Name | Permission | Parameter | + |:--------|:-----------|:----------| + | Products | modify | `store_v2_products` | + | Products | read-only | `store_v2_products_read_only` | + + ### Authentication header + + | Header | Argument | Description | + |:-------|:---------|:------------| + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | + + ### Further reading + + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). + + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). + + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). + type: apiKey + in: header diff --git a/reference/catalog/product-variant-options_catalog.v3.yml b/reference/catalog/product-variant-options_catalog.v3.yml new file mode 100644 index 000000000..92c1b79fe --- /dev/null +++ b/reference/catalog/product-variant-options_catalog.v3.yml @@ -0,0 +1,2469 @@ +openapi: '3.0.3' +info: + title: Catalog - Product Variant Options + description: |- + > The Catalog API manages products, categories, brands, bulk pricing rules, and more. To learn more about catalog resources, see the [Catalog Overview](/docs/store-operations/catalog). + + Product Variant Options represent the different facets of a product. For example, size, color, fabric. Variant Option values are the actual sizes, colors, fabrics, that are available. [Product Variants]() consist of combinations of Variant Option values. + + The following table illustrates the relationship between Variant Options and Variant Option values using a line of signature sneakers as an example. + + | Variant options | Variant option values | No. of variants | + |:----------------|:----------------------|----------------:| + | size (US Women's) | 6, 6.5, 7, 7.5, 8, 8.5, 9, 9.5, 10, 10.5 | 10 | + | upper material | canvas, marine plastic, leather | 3 | + | upper color | brick, azul, gold | 3 | + | sole color | charcoal, white, azul | 3 | + | | | **270** | + + + Our Catalog Product Variant Options endpoints let you work with both Variant Options and Variant Option Values. + + > To learn more about authenticating Catalog endpoints, locate the **Authentication** section at the top of each endpoint, then click **Show Details**. + + ## Resources + + ### Webhooks + Learn more about [Product webhook events](/docs/integrations/webhooks/events#products). + + ### Additional Catalog endpoints + * [Brands](/docs/rest-catalog/brands) + * [Categories](/docs/rest-catalog/categories) + * [Category Trees](/docs/rest-catalog/category-trees) + * [Products](/docs/rest-catalog/products) + * [Product Modifiers](/docs/rest-catalog/product-modifiers) + * [Product Variants](/docs/rest-catalog/product-variants) + + termsOfService: 'https://www.bigcommerce.com/terms' + contact: + name: BigCommerce + url: 'https://www.bigcommerce.com' + email: support@bigcommerce.com + version: '' +servers: + - url: 'https://api.bigcommerce.com/stores/{store_hash}/v3' + variables: + store_hash: + default: store_hash + description: Permanent ID of the BigCommerce store. + description: BigCommerce API Gateway +security: + - X-Auth-Token: [] +tags: + - name: Product Variant Options + - name: Values +paths: + '/catalog/products/{product_id}/options': + get: + tags: + - Product Variant Options + summary: Get All Product Variant Options + description: 'Returns a list of product *Variant Options*. Optional parameters can be passed in. ' + operationId: getOptions + parameters: + - name: page + in: query + description: Specifies the page number in a limited (paginated) list of products. + schema: + type: integer + - name: limit + in: query + description: Controls the number of items per page in a limited (paginated) list of products. + schema: + type: integer + - name: include_fields + in: query + description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' + schema: + type: string + - name: exclude_fields + in: query + description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + title: Option Collection Response + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/productOption_Full' + meta: + $ref: '#/components/schemas/metaCollection_Full' + description: Get all product options + '404': + description: | + The resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + post: + tags: + - Product Variant Options + summary: Create a Product Variant Option + description: |- + Creates a *Variant Option*. + + **Required Fields** + * display_name + * type + * option_values + + **Read-Only Fields** + * id + + **Limits** + * 255 characters option name length. + + **Notes** + + * Only one variant option at a time can be created; individual variant options will contain an array of multiple values. + * There are several examples listed below that create options, but the SKUs are not updated and they are not a variant on the product. Variant SKUs must be created with a separate request. + * Variant options will show on the storefront as an option that can be selected by the customer. A request like this could be used to add new choices to a variant that has already been created. + * If more than one variant needs to be created, use the [Create a Product](/docs/rest-catalog/products#create-a-product) endpoint. + operationId: createOption + parameters: + - $ref: '#/components/parameters/ContentType' + requestBody: + content: + application/json: + schema: + title: Option Post + description: The model for a POST to create options on a product. + allOf: + - title: Option Base + description: Common Option properties. + properties: + product_id: + type: integer + description: | + The unique numerical ID of the product to which the option belongs. + example: 4 + x-required: + - post + - put + display_name: + maxLength: 255 + minLength: 1 + type: string + description: | + The name of the option shown on the storefront. + example: Add-a-$5-Donation1535042499-187 + x-required: + - post + - put + type: + type: string + description: | + The type of option, which determines how it will display on the storefront. Acceptable values: `radio_buttons`, `rectangles`, `dropdown`, `product_list`, `product_list_with_images`, `swatch`. For reference, the former v2 API values are: RB = radio_buttons, RT = rectangles, S = dropdown, P = product_list, PI = product_list_with_images, CS = swatch. + enum: + - radio_buttons + - rectangles + - dropdown + - product_list + - product_list_with_images + - swatch + x-required: + - post + - put + config: + title: Option Config + type: object + description: The values for option config can vary based on the Modifier created. + properties: + default_value: + type: string + description: | + (date, text, multi_line_text, numbers_only_text) The default value. Shown on a date option as an ISO-8601–formatted string, or on a text option as a string. + checked_by_default: + type: boolean + description: | + (checkbox) Flag for setting the checkbox to be checked by default. + checkbox_label: + type: string + description: | + (checkbox) Label displayed for the checkbox option. + date_limited: + type: boolean + description: | + (date) Flag to limit the dates allowed to be entered on a date option. + date_limit_mode: + type: string + description: | + (date) The type of limit that is allowed to be entered on a date option. + example: range + enum: + - earliest + - range + - latest + date_earliest_value: + type: string + description: | + (date) The earliest date allowed to be entered on the date option, as an ISO-8601 formatted string. + format: date-time + example: '2018-08-31T00:00:00+00:00' + date_latest_value: + type: string + description: | + (date) The latest date allowed to be entered on the date option, as an ISO-8601 formatted string. + format: date-time + example: '2019-01-01T00:00:00+00:00' + file_types_mode: + type: string + description: | + (file) The kind of restriction on the file types that can be uploaded with a file upload option. Values: `specific` - restricts uploads to particular file types; `all` - allows all file types. + example: specific + enum: + - specific + - all + file_types_supported: + type: array + description: | + (file) The type of files allowed to be uploaded if the `file_type_option` is set to `specific`. Values: + `images` - Allows upload of image MIME types (`bmp`, `gif`, `jpg`, `jpeg`, `jpe`, `jif`, `jfif`, `jfi`, `png`, `wbmp`, `xbm`, `tiff`). `documents` - Allows upload of document MIME types (`txt`, `pdf`, `rtf`, `doc`, `docx`, `xls`, `xlsx`, `accdb`, `mdb`, `one`, `pps`, `ppsx`, `ppt`, `pptx`, `pub`, `odt`, `ods`, `odp`, `odg`, `odf`). + `other` - Allows file types defined in the `file_types_other` array. + example: + - images + - documents + - other + items: + type: string + file_types_other: + type: array + description: | + (file) A list of other file types allowed with the file upload option. + example: + - pdf + - txt + items: + type: string + file_max_size: + type: integer + description: | + (file) The maximum size for a file that can be used with the file upload option. This will still be limited by the server. + example: 5 + text_characters_limited: + type: boolean + description: | + (text, multi_line_text) Flag to validate the length of a text or multi-line text input. + text_min_length: + type: integer + description: | + (text, multi_line_text) The minimum length allowed for a text or multi-line text option. + example: 1 + text_max_length: + type: integer + description: | + (text, multi_line_text) The maximum length allowed for a text or multi line text option. + example: 55 + text_lines_limited: + type: boolean + description: | + (multi_line_text) Flag to validate the maximum number of lines allowed on a multi-line text input. + example: true + text_max_lines: + type: integer + description: | + (multi_line_text) The maximum number of lines allowed on a multi-line text input. + example: 4 + number_limited: + type: boolean + description: | + (numbers_only_text) Flag to limit the value of a number option. + example: true + number_limit_mode: + type: string + description: | + (numbers_only_text) The type of limit on values entered for a number option. + example: lowest + enum: + - lowest + - highest + - range + number_lowest_value: + type: number + description: | + (numbers_only_text) The lowest allowed value for a number option if `number_limited` is true. + example: 100 + number_highest_value: + type: number + description: | + (numbers_only_text) The highest allowed value for a number option if `number_limited` is true. + number_integers_only: + type: boolean + description: | + (numbers_only_text) Flag to limit the input on a number option to whole numbers only. + example: false + product_list_adjusts_inventory: + type: boolean + description: | + (product_list, product_list_with_images) Flag for automatically adjusting inventory on a product included in the list. + product_list_adjusts_pricing: + type: boolean + description: | + (product_list, product_list_with_images) Flag to add the optional product's price to the main product's price. + product_list_shipping_calc: + type: string + description: | + (product_list, product_list_with_images) How to factor the optional product's weight and package dimensions into the shipping quote. Values: `none` - don't adjust; `weight` - use shipping weight only; `package` - use weight and dimensions. + example: weight + enum: + - none + - weight + - package + sort_order: + type: integer + description: 'Order in which the option is displayed on the storefront. ' + example: 1 + option_values: + minItems: 1 + type: array + x-required: + - post + - put + items: + title: Option Value + allOf: + - title: Option Value Base + description: Common Option Value properties. + properties: + is_default: + type: boolean + description: | + The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. + example: false + label: + type: string + description: | + The text display identifying the value on the storefront. Required in a /POST. + example: Green + x-required: + - post + sort_order: + maximum: 2147483647 + minimum: -2147483648 + type: integer + description: | + The order in which the value will be displayed on the product page. Required in a /POST. + example: 0 + x-required: + - post + value_data: + type: object + properties: {} + description: | + Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. + required: + - label + - sort_order + - properties: + id: + type: integer + description: | + The unique numeric ID of the value; increments sequentially. + type: object + image_url: + type: string + description: Publicly available image url + type: object + required: true + responses: + '200': + description: '' + content: + application/json: + schema: + title: Option Response + type: object + properties: + data: + title: Option + type: object + allOf: + - title: Option Base + description: Common Option properties. + type: object + properties: + id: + type: integer + description: | + The unique numerical ID of the option, increments sequentially. + example: 55 + x-nullable: true + product_id: + type: integer + description: | + The unique numerical ID of the product to which the option belongs. + example: 4 + x-required: + - post + - put + display_name: + maxLength: 255 + minLength: 1 + type: string + description: | + The name of the option shown on the storefront. + example: Add-a-$5-Donation1535042499-187 + x-required: + - post + - put + type: + type: string + description: | + The type of option, which determines how it will display on the storefront. Acceptable values: `radio_buttons`, `rectangles`, `dropdown`, `product_list`, `product_list_with_images`, `swatch`. For reference, the former v2 API values are: RB = radio_buttons, RT = rectangles, S = dropdown, P = product_list, PI = product_list_with_images, CS = swatch. + enum: + - radio_buttons + - rectangles + - dropdown + - product_list + - product_list_with_images + - swatch + x-required: + - post + - put + config: + title: Option Config + type: object + description: The values for option config can vary based on the Modifier created. + properties: + default_value: + type: string + description: | + (date, text, multi_line_text, numbers_only_text) The default value. Shown on a date option as an ISO-8601–formatted string, or on a text option as a string. + checked_by_default: + type: boolean + description: | + (checkbox) Flag for setting the checkbox to be checked by default. + checkbox_label: + type: string + description: | + (checkbox) Label displayed for the checkbox option. + date_limited: + type: boolean + description: | + (date) Flag to limit the dates allowed to be entered on a date option. + date_limit_mode: + type: string + description: | + (date) The type of limit that is allowed to be entered on a date option. + example: range + enum: + - earliest + - range + - latest + date_earliest_value: + type: string + description: | + (date) The earliest date allowed to be entered on the date option, as an ISO-8601 formatted string. + format: date-time + date_latest_value: + type: string + description: | + (date) The latest date allowed to be entered on the date option, as an ISO-8601 formatted string. + format: date-time + file_types_mode: + type: string + description: | + (file) The kind of restriction on the file types that can be uploaded with a file upload option. Values: `specific` - restricts uploads to particular file types; `all` - allows all file types. + example: specific + enum: + - specific + - all + file_types_supported: + type: array + description: | + (file) The type of files allowed to be uploaded if the `file_type_option` is set to `specific`. Values: + `images` - Allows upload of image MIME types (`bmp`, `gif`, `jpg`, `jpeg`, `jpe`, `jif`, `jfif`, `jfi`, `png`, `wbmp`, `xbm`, `tiff`). `documents` - Allows upload of document MIME types (`txt`, `pdf`, `rtf`, `doc`, `docx`, `xls`, `xlsx`, `accdb`, `mdb`, `one`, `pps`, `ppsx`, `ppt`, `pptx`, `pub`, `odt`, `ods`, `odp`, `odg`, `odf`). + `other` - Allows file types defined in the `file_types_other` array. + items: + type: string + example: 'images, documents, other' + file_types_other: + type: array + description: | + (file) A list of other file types allowed with the file upload option. + items: + type: string + example: pdf + file_max_size: + type: integer + description: | + (file) The maximum size for a file that can be used with the file upload option. This will still be limited by the server. + example: 5 + text_characters_limited: + type: boolean + description: | + (text, multi_line_text) Flag to validate the length of a text or multi-line text input. + text_min_length: + type: integer + description: | + (text, multi_line_text) The minimum length allowed for a text or multi-line text option. + example: 1 + text_max_length: + type: integer + description: | + (text, multi_line_text) The maximum length allowed for a text or multi line text option. + example: 55 + text_lines_limited: + type: boolean + description: | + (multi_line_text) Flag to validate the maximum number of lines allowed on a multi-line text input. + example: true + text_max_lines: + type: integer + description: | + (multi_line_text) The maximum number of lines allowed on a multi-line text input. + example: 4 + number_limited: + type: boolean + description: | + (numbers_only_text) Flag to limit the value of a number option. + example: true + number_limit_mode: + type: string + description: | + (numbers_only_text) The type of limit on values entered for a number option. + example: lowest + enum: + - lowest + - highest + - range + number_lowest_value: + type: number + description: | + (numbers_only_text) The lowest allowed value for a number option if `number_limited` is true. + example: 100 + number_highest_value: + type: number + description: | + (numbers_only_text) The highest allowed value for a number option if `number_limited` is true. + number_integers_only: + type: boolean + description: | + (numbers_only_text) Flag to limit the input on a number option to whole numbers only. + example: false + product_list_adjusts_inventory: + type: boolean + description: | + (product_list, product_list_with_images) Flag for automatically adjusting inventory on a product included in the list. + product_list_adjusts_pricing: + type: boolean + description: | + (product_list, product_list_with_images) Flag to add the optional product's price to the main product's price. + product_list_shipping_calc: + type: string + description: | + (product_list, product_list_with_images) How to factor the optional product's weight and package dimensions into the shipping quote. Values: `none` - don't adjust; `weight` - use shipping weight only; `package` - use weight and dimensions. + example: weight + enum: + - none + - weight + - package + sort_order: + type: integer + description: 'Order in which the option is displayed on the storefront. ' + example: 1 + option_values: + minItems: 1 + type: array + x-required: + - post + - put + items: + title: Option Value + allOf: + - title: Option Value Base + description: Common Option Value properties. + properties: + is_default: + type: boolean + description: | + The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. + example: false + label: + type: string + description: | + The text display identifying the value on the storefront. Required in a /POST. + example: Green + x-required: + - post + sort_order: + maximum: 2147483647 + minimum: -2147483648 + type: integer + description: | + The order in which the value will be displayed on the product page. Required in a /POST. + example: 0 + x-required: + - post + value_data: + type: object + properties: {} + description: | + Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. + required: + - label + - sort_order + - properties: + id: + type: integer + description: | + The unique numeric ID of the value; increments sequentially. + type: object + image_url: + type: string + description: Publicly available image url + - type: object + properties: + name: + type: string + description: | + The unique option name, auto-generated from the display name, a timestamp, and the product ID. + example: Add-a-$5-Donation1535042499-187 + meta: + title: Meta + type: object + properties: {} + description: Empty meta object; may be used later. + examples: + example-1: + value: + data: + id: 55 + product_id: 4 + display_name: Add-a-$5-Donation1535042499-187 + type: radio_buttons + config: + default_value: string + checked_by_default: true + checkbox_label: string + date_limited: true + date_limit_mode: earliest + date_earliest_value: '2022-08-24T00:00:00+00:00' + date_latest_value: '2022-08-27T00:00:00+00:00' + file_types_mode: specific + file_types_supported: + - 'images, documents, other' + file_types_other: + - pdf + file_max_size: 5 + text_characters_limited: true + text_min_length: 1 + text_max_length: 55 + text_lines_limited: true + text_max_lines: 4 + number_limited: true + number_limit_mode: lowest + number_lowest_value: 100 + number_highest_value: 0 + number_integers_only: false + product_list_adjusts_inventory: true + product_list_adjusts_pricing: true + product_list_shipping_calc: none + sort_order: 1 + option_values: + - is_default: false + label: Green + sort_order: 0 + value_data: {} + id: 0 + image_url: string + name: Add-a-$5-Donation1535042499-187 + meta: {} + example-2: + value: + data: + id: 220 + product_id: 192 + name: Color (Colors only) + display_name: Color + type: swatch + sort_order: 0 + option_values: + - id: 174 + label: Beige + sort_order: 1 + value_data: + colors: + - '#FAFAEB' + is_default: false + - id: 175 + label: Grey + sort_order: 2 + value_data: + colors: + - '#BDBDBD' + is_default: false + - id: 176 + label: Black + sort_order: 3 + value_data: + colors: + - '#000000' + is_default: false + - id: 189 + label: Black-Walnut + sort_order: 4 + value_data: + colors: + - '#e80ee8' + is_default: false + config: {} + meta: {} + '409': + description: | + Option was in conflict with another option. This is the result of duplicate unique fields, such as `name`. + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + '422': + description: | + Option was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + x-codegen-request-body-name: Option + parameters: + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/ProductIdParam' + '/catalog/products/{product_id}/options/{option_id}': + get: + tags: + - Product Variant Options + summary: Get a Product Variant Option + description: Returns a single *Variant Option*. Optional parameters can be passed in. + operationId: getOptionById + parameters: + - name: include_fields + in: query + description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' + schema: + type: string + - name: exclude_fields + in: query + description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + title: Option Response + type: object + properties: + data: + $ref: '#/components/schemas/productOption_Full' + meta: + $ref: '#/components/schemas/metaEmpty_Full' + '404': + description: | + The resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + put: + tags: + - Product Variant Options + summary: Update a Product Variant Option + description: |- + Updates a *Variant Option*. + + **Read-Only Fields** + * id + operationId: updateOption + parameters: + - $ref: '#/components/parameters/ContentType' + requestBody: + content: + application/json: + schema: + title: Option Put + description: The model for a PUT to update options on a product. + allOf: + - title: Option Base + type: object + properties: + id: + type: integer + description: | + The unique numerical ID of the option, increments sequentially. + nullable: true + example: 55 + product_id: + type: integer + description: | + The unique numerical ID of the product to which the option belongs. + example: 4 + x-required: + - post + - put + display_name: + maxLength: 255 + minLength: 1 + type: string + description: | + The name of the option shown on the storefront. + example: Add-a-$5-Donation1535042499-187 + x-required: + - post + - put + type: + type: string + description: | + The type of option, which determines how it will display on the storefront. Acceptable values: `radio_buttons`, `rectangles`, `dropdown`, `product_list`, `product_list_with_images`, `swatch`. For reference, the former v2 API values are: RB = radio_buttons, RT = rectangles, S = dropdown, P = product_list, PI = product_list_with_images, CS = swatch. + enum: + - radio_buttons + - rectangles + - dropdown + - product_list + - product_list_with_images + - swatch + x-required: + - post + - put + config: + title: Option Config + type: object + properties: + default_value: + type: string + description: | + (date, text, multi_line_text, numbers_only_text) The default value. Shown on a date option as an ISO-8601–formatted string, or on a text option as a string. + checked_by_default: + type: boolean + description: | + (checkbox) Flag for setting the checkbox to be checked by default. + checkbox_label: + type: string + description: | + (checkbox) Label displayed for the checkbox option. + date_limited: + type: boolean + description: | + (date) Flag to limit the dates allowed to be entered on a date option. + date_limit_mode: + type: string + description: | + (date) The type of limit that is allowed to be entered on a date option. + example: range + enum: + - earliest + - range + - latest + date_earliest_value: + type: string + description: | + (date) The earliest date allowed to be entered on the date option, as an ISO-8601 formatted string. + format: date-time + example: '2018-08-31T00:00:00+00:00' + date_latest_value: + type: string + description: | + (date) The latest date allowed to be entered on the date option, as an ISO-8601 formatted string. + format: date-time + example: '2019-01-01T00:00:00+00:00' + file_types_mode: + type: string + description: | + (file) The kind of restriction on the file types that can be uploaded with a file upload option. Values: `specific` - restricts uploads to particular file types; `all` - allows all file types. + example: specific + enum: + - specific + - all + file_types_supported: + type: array + description: | + (file) The type of files allowed to be uploaded if the `file_type_option` is set to `specific`. Values: + `images` - Allows upload of image MIME types (`bmp`, `gif`, `jpg`, `jpeg`, `jpe`, `jif`, `jfif`, `jfi`, `png`, `wbmp`, `xbm`, `tiff`). `documents` - Allows upload of document MIME types (`txt`, `pdf`, `rtf`, `doc`, `docx`, `xls`, `xlsx`, `accdb`, `mdb`, `one`, `pps`, `ppsx`, `ppt`, `pptx`, `pub`, `odt`, `ods`, `odp`, `odg`, `odf`). + `other` - Allows file types defined in the `file_types_other` array. + example: + - images + - documents + - other + items: + type: string + file_types_other: + type: array + description: | + (file) A list of other file types allowed with the file upload option. + example: + - pdf + - txt + items: + type: string + file_max_size: + type: integer + description: | + (file) The maximum size for a file that can be used with the file upload option. This will still be limited by the server. + example: 5 + text_characters_limited: + type: boolean + description: | + (text, multi_line_text) Flag to validate the length of a text or multi-line text input. + text_min_length: + type: integer + description: | + (text, multi_line_text) The minimum length allowed for a text or multi-line text option. + example: 1 + text_max_length: + type: integer + description: | + (text, multi_line_text) The maximum length allowed for a text or multi line text option. + example: 55 + text_lines_limited: + type: boolean + description: | + (multi_line_text) Flag to validate the maximum number of lines allowed on a multi-line text input. + example: true + text_max_lines: + type: integer + description: | + (multi_line_text) The maximum number of lines allowed on a multi-line text input. + example: 4 + number_limited: + type: boolean + description: | + (numbers_only_text) Flag to limit the value of a number option. + example: true + number_limit_mode: + type: string + description: | + (numbers_only_text) The type of limit on values entered for a number option. + example: lowest + enum: + - lowest + - highest + - range + number_lowest_value: + type: number + description: | + (numbers_only_text) The lowest allowed value for a number option if `number_limited` is true. + example: 100 + number_highest_value: + type: number + description: | + (numbers_only_text) The highest allowed value for a number option if `number_limited` is true. + number_integers_only: + type: boolean + description: | + (numbers_only_text) Flag to limit the input on a number option to whole numbers only. + example: false + product_list_adjusts_inventory: + type: boolean + description: | + (product_list, product_list_with_images) Flag for automatically adjusting inventory on a product included in the list. + product_list_adjusts_pricing: + type: boolean + description: | + (product_list, product_list_with_images) Flag to add the optional product's price to the main product's price. + product_list_shipping_calc: + type: string + description: | + (product_list, product_list_with_images) How to factor the optional product's weight and package dimensions into the shipping quote. Values: `none` - don't adjust; `weight` - use shipping weight only; `package` - use weight and dimensions. + example: weight + enum: + - none + - weight + - package + description: The values for option config can vary based on the Modifier created. + sort_order: + type: integer + description: 'Order in which the option is displayed on the storefront. ' + example: 1 + option_values: + minItems: 1 + type: array + items: + title: Option Value + type: object + allOf: + - title: Option Value Base + required: + - label + - sort_order + type: object + properties: + is_default: + type: boolean + description: | + The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. + example: false + label: + type: string + description: | + The text display identifying the value on the storefront. Required in a /POST. + example: Green + x-required: + - post + sort_order: + maximum: 2147483647 + minimum: -2147483648 + type: integer + description: | + The order in which the value will be displayed on the product page. Required in a /POST. + example: 0 + x-required: + - post + value_data: + type: object + properties: {} + description: | + Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. + description: Common Option Value properties. + - type: object + properties: + id: + type: integer + description: | + The unique numeric ID of the value; increments sequentially. + x-required: + - post + - put + image_url: + type: string + description: Publicly available image url + description: Common Option properties. + required: true + responses: + '200': + description: '' + content: + application/json: + schema: + title: Option Response + type: object + properties: + data: + title: Option + type: object + allOf: + - title: Option Base + type: object + properties: + id: + type: integer + description: | + The unique numerical ID of the option, increments sequentially. + example: 55 + x-nullable: true + product_id: + type: integer + description: | + The unique numerical ID of the product to which the option belongs. + example: 4 + x-required: + - post + - put + display_name: + maxLength: 255 + minLength: 1 + type: string + description: | + The name of the option shown on the storefront. + example: Add-a-$5-Donation1535042499-187 + x-required: + - post + - put + type: + type: string + description: | + The type of option, which determines how it will display on the storefront. Acceptable values: `radio_buttons`, `rectangles`, `dropdown`, `product_list`, `product_list_with_images`, `swatch`. For reference, the former v2 API values are: RB = radio_buttons, RT = rectangles, S = dropdown, P = product_list, PI = product_list_with_images, CS = swatch. + enum: + - radio_buttons + - rectangles + - dropdown + - product_list + - product_list_with_images + - swatch + x-required: + - post + - put + config: + title: Option Config + type: object + properties: + default_value: + type: string + description: | + (date, text, multi_line_text, numbers_only_text) The default value. Shown on a date option as an ISO-8601–formatted string, or on a text option as a string. + checked_by_default: + type: boolean + description: | + (checkbox) Flag for setting the checkbox to be checked by default. + checkbox_label: + type: string + description: | + (checkbox) Label displayed for the checkbox option. + date_limited: + type: boolean + description: | + (date) Flag to limit the dates allowed to be entered on a date option. + date_limit_mode: + type: string + description: | + (date) The type of limit that is allowed to be entered on a date option. + example: range + enum: + - earliest + - range + - latest + date_earliest_value: + type: string + description: | + (date) The earliest date allowed to be entered on the date option, as an ISO-8601 formatted string. + format: date + date_latest_value: + type: string + description: | + (date) The latest date allowed to be entered on the date option, as an ISO-8601 formatted string. + format: date + file_types_mode: + type: string + description: | + (file) The kind of restriction on the file types that can be uploaded with a file upload option. Values: `specific` - restricts uploads to particular file types; `all` - allows all file types. + example: specific + enum: + - specific + - all + file_types_supported: + type: array + description: | + (file) The type of files allowed to be uploaded if the `file_type_option` is set to `specific`. Values: + `images` - Allows upload of image MIME types (`bmp`, `gif`, `jpg`, `jpeg`, `jpe`, `jif`, `jfif`, `jfi`, `png`, `wbmp`, `xbm`, `tiff`). `documents` - Allows upload of document MIME types (`txt`, `pdf`, `rtf`, `doc`, `docx`, `xls`, `xlsx`, `accdb`, `mdb`, `one`, `pps`, `ppsx`, `ppt`, `pptx`, `pub`, `odt`, `ods`, `odp`, `odg`, `odf`). + `other` - Allows file types defined in the `file_types_other` array. + items: + type: string + example: 'images, documents, other' + file_types_other: + type: array + description: | + (file) A list of other file types allowed with the file upload option. + items: + type: string + example: pdf + file_max_size: + type: integer + description: | + (file) The maximum size for a file that can be used with the file upload option. This will still be limited by the server. + example: 5 + text_characters_limited: + type: boolean + description: | + (text, multi_line_text) Flag to validate the length of a text or multi-line text input. + text_min_length: + type: integer + description: | + (text, multi_line_text) The minimum length allowed for a text or multi-line text option. + example: 1 + text_max_length: + type: integer + description: | + (text, multi_line_text) The maximum length allowed for a text or multi line text option. + example: 55 + text_lines_limited: + type: boolean + description: | + (multi_line_text) Flag to validate the maximum number of lines allowed on a multi-line text input. + example: true + text_max_lines: + type: integer + description: | + (multi_line_text) The maximum number of lines allowed on a multi-line text input. + example: 4 + number_limited: + type: boolean + description: | + (numbers_only_text) Flag to limit the value of a number option. + example: true + number_limit_mode: + type: string + description: | + (numbers_only_text) The type of limit on values entered for a number option. + example: lowest + enum: + - lowest + - highest + - range + number_lowest_value: + type: number + description: | + (numbers_only_text) The lowest allowed value for a number option if `number_limited` is true. + example: 100 + number_highest_value: + type: number + description: | + (numbers_only_text) The highest allowed value for a number option if `number_limited` is true. + number_integers_only: + type: boolean + description: | + (numbers_only_text) Flag to limit the input on a number option to whole numbers only. + example: false + product_list_adjusts_inventory: + type: boolean + description: | + (product_list, product_list_with_images) Flag for automatically adjusting inventory on a product included in the list. + product_list_adjusts_pricing: + type: boolean + description: | + (product_list, product_list_with_images) Flag to add the optional product's price to the main product's price. + product_list_shipping_calc: + type: string + description: | + (product_list, product_list_with_images) How to factor the optional product's weight and package dimensions into the shipping quote. Values: `none` - don't adjust; `weight` - use shipping weight only; `package` - use weight and dimensions. + example: weight + enum: + - none + - weight + - package + description: The values for option config can vary based on the Modifier created. + sort_order: + type: integer + description: 'Order in which the option is displayed on the storefront. ' + example: 1 + option_values: + minItems: 1 + type: array + items: + title: Option Value + type: object + allOf: + - title: Option Value Base + required: + - label + - sort_order + type: object + properties: + is_default: + type: boolean + description: | + The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. + example: false + label: + type: string + description: | + The text display identifying the value on the storefront. Required in a /POST. + example: Green + x-required: + - post + sort_order: + maximum: 2147483647 + minimum: -2147483648 + type: integer + description: | + The order in which the value will be displayed on the product page. Required in a /POST. + example: 0 + x-required: + - post + value_data: + type: object + properties: {} + description: | + Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. + x-nullable: true + description: Common Option Value properties. + - type: object + properties: + id: + type: integer + description: | + The unique numeric ID of the value; increments sequentially. + x-required: + - post + - put + image_url: + type: string + description: Publicly available image url + description: Common Option properties. + - type: object + properties: + name: + type: string + description: | + The unique option name, auto-generated from the display name, a timestamp, and the product ID. + example: Add-a-$5-Donation1535042499-187 + meta: + $ref: '#/components/schemas/metaEmpty_Full' + example: + data: + id: 220 + product_id: 192 + name: Color (Colors only) + display_name: Color + type: swatch + sort_order: 0 + option_values: + - id: 174 + label: Beige + sort_order: 1 + value_data: + colors: + - '#FAFAEB' + is_default: false + - id: 175 + label: Grey + sort_order: 2 + value_data: + colors: + - '#BDBDBD' + is_default: false + - id: 176 + label: Black + sort_order: 3 + value_data: + colors: + - '#000000' + is_default: false + - id: 189 + label: Black-Walnut + sort_order: 4 + value_data: + colors: + - '#e80ee8' + is_default: false + config: {} + meta: {} + '409': + description: | + The `Option` was in conflict with another option. This is the result of duplicate unique fields, such as `name`. + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + '422': + description: | + The `Option` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + x-codegen-request-body-name: option + delete: + tags: + - Product Variant Options + summary: Delete a Product Variant Option + description: Deletes a *Variant Option*. + operationId: deleteOptionById + responses: + '204': + description: '' + content: {} + parameters: + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/ProductIdParam' + - $ref: '#/components/parameters/OptionIdParam' + '/catalog/products/{product_id}/options/{option_id}/values': + get: + tags: + - Values + summary: Get All Product Variant Option Values + description: Returns a list of all *Variant Option Values*. Optional parameters can be passed in. + operationId: getOptionValues + parameters: + - name: option_id + in: path + description: | + The ID of the `Option`. + required: true + schema: + type: integer + + - name: include_fields + in: query + description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' + schema: + type: string + - name: exclude_fields + in: query + description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' + schema: + type: string + - name: page + in: query + description: Specifies the page number in a limited (paginated) list of products. + schema: + type: integer + - name: limit + in: query + description: Controls the number of items per page in a limited (paginated) list of products. + schema: + type: integer + responses: + '200': + description: '' + content: + application/json: + schema: + title: Option Value Collection Response + type: object + properties: + data: + type: array + items: + title: Option Value + type: object + allOf: + - title: Option Value Base + required: + - label + - sort_order + type: object + properties: + is_default: + type: boolean + description: | + The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. + example: false + label: + type: string + description: | + The text display identifying the value on the storefront. Required in a /POST. + example: Green + x-required: + - post + sort_order: + maximum: 2147483647 + minimum: -2147483648 + type: integer + description: | + The order in which the value will be displayed on the product page. Required in a /POST. + example: 0 + x-required: + - post + value_data: + type: object + properties: {} + description: | + Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. + x-nullable: true + description: Common Option Value properties. + - type: object + properties: + id: + type: integer + description: | + The unique numeric ID of the value; increments sequentially. + meta: + $ref: '#/components/schemas/metaCollection_Full' + description: Get Option Values response. + example: + data: + - id: 174 + label: Beige + sort_order: 1 + value_data: + colors: + - '#FAFAEB' + is_default: false + - id: 175 + label: Grey + sort_order: 2 + value_data: + colors: + - '#BDBDBD' + is_default: false + - id: 176 + label: Black + sort_order: 3 + value_data: + colors: + - '#000000' + is_default: false + - id: 189 + label: Black-Walnut + sort_order: 4 + value_data: + colors: + - '#e80ee8' + is_default: false + meta: + pagination: + total: 4 + count: 4 + per_page: 50 + current_page: 1 + total_pages: 1 + links: + current: '?page=1&limit=50' + post: + tags: + - Values + summary: Create a Product Variant Option Value + description: |- + Creates a *Variant Option Value*. + + **Required Fields** + * label + * sort_order + + **Read-Only Fields** + * id + + **Limits** + * 250 option values per option limit. + operationId: createOptionValue + parameters: + - $ref: '#/components/parameters/ContentType' + - name: option_id + in: path + description: | + The ID of the `Option`. + required: true + schema: + type: integer + requestBody: + content: + application/json: + schema: + title: Option Value Post + description: The model for a POST to create option values on a product. + allOf: + - title: Option Value Base + required: + - label + - sort_order + type: object + properties: + is_default: + type: boolean + description: | + The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. + example: false + label: + type: string + description: | + The text display identifying the value on the storefront. Required in a /POST. + example: Green + x-required: + - post + sort_order: + maximum: 2147483647 + minimum: -2147483648 + type: integer + description: | + The order in which the value will be displayed on the product page. Required in a /POST. + example: 0 + x-required: + - post + value_data: + type: object + properties: {} + description: | + Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. + description: Common Option Value properties. + required: true + responses: + '200': + description: '' + content: + application/json: + schema: + title: Option Value Response + type: object + properties: + data: + title: Option Value + type: object + allOf: + - title: Option Value Base + required: + - label + - sort_order + type: object + properties: + is_default: + type: boolean + description: | + The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. + example: false + label: + type: string + description: | + The text display identifying the value on the storefront. Required in a /POST. + example: Green + x-required: + - post + sort_order: + maximum: 2147483647 + minimum: -2147483648 + type: integer + description: | + The order in which the value will be displayed on the product page. Required in a /POST. + example: 0 + x-required: + - post + value_data: + type: object + properties: {} + description: | + Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. + x-nullable: true + description: Common Option Value properties. + - type: object + properties: + id: + type: integer + description: | + The unique numeric ID of the value; increments sequentially. + meta: + $ref: '#/components/schemas/metaEmpty_Full' + example: + data: + id: 44 + label: Pick a color + sort_order: 9 + value_data: + colors: + - '#123c91, #FFFF00, #397a44' + is_default: false + '422': + description: | + The `OptionValue` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + x-codegen-request-body-name: OptionValue + parameters: + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/ProductIdParam' + - $ref: '#/components/parameters/OptionIdParam' + '/catalog/products/{product_id}/options/{option_id}/values/{value_id}': + get: + tags: + - Values + summary: Get a Product Variant Option Value + description: Returns a single *Variant Option Value*. Optional parameters can be passed in. + operationId: getOptionValueById + parameters: + - name: option_id + in: path + description: | + The ID of the `Option`. + required: true + schema: + type: integer + - name: value_id + in: path + description: | + The ID of the `Modifier/Option Value`. + required: true + schema: + type: integer + + - name: include_fields + in: query + description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' + schema: + type: string + - name: exclude_fields + in: query + description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + title: Option Value Response + type: object + properties: + data: + title: Option Value + type: object + allOf: + - title: Option Value Base + required: + - label + - sort_order + type: object + properties: + is_default: + type: boolean + description: | + The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. + example: false + label: + type: string + description: | + The text display identifying the value on the storefront. Required in a /POST. + example: Green + x-required: + - post + sort_order: + maximum: 2147483647 + minimum: -2147483648 + type: integer + description: | + The order in which the value will be displayed on the product page. Required in a /POST. + example: 0 + x-required: + - post + value_data: + type: object + properties: {} + description: | + Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. + x-nullable: true + description: Common Option Value properties. + - type: object + properties: + id: + type: integer + description: | + The unique numeric ID of the value; increments sequentially. + meta: + $ref: '#/components/schemas/metaEmpty_Full' + example: + data: + id: 44 + label: Pick a color + sort_order: 9 + value_data: + colors: + - '#123c91, #FFFF00, #397a44' + is_default: false + '404': + description: | + The resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + put: + tags: + - Values + summary: Update a Product Variant Option Value + description: |- + Updates a *Variant Option Value*. + + **Read-Only Fields** + * id + operationId: updateOptionValue + parameters: + - $ref: '#/components/parameters/ContentType' + - name: option_id + in: path + description: | + The ID of the `Option`. + required: true + schema: + type: integer + - name: value_id + in: path + description: | + The ID of the `Modifier/Option Value`. + required: true + schema: + type: integer + requestBody: + description: | + A BigCommerce `OptionValue` object. + content: + application/json: + schema: + title: Option Value Put + description: The model for a PUT to update option values on a product. + allOf: + - title: Option Value Base + required: + - label + - sort_order + type: object + properties: + is_default: + type: boolean + description: | + The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. + example: false + label: + type: string + description: | + The text display identifying the value on the storefront. Required in a /POST. + example: Green + x-required: + - post + sort_order: + maximum: 2147483647 + minimum: -2147483648 + type: integer + description: | + The order in which the value will be displayed on the product page. Required in a /POST. + example: 0 + x-required: + - post + value_data: + type: object + properties: {} + description: | + Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. + description: Common Option Value properties. + - type: object + properties: + id: + type: integer + description: | + The unique numeric ID of the value; increments sequentially. + x-required: + - put + required: true + responses: + '200': + description: '' + content: + application/json: + schema: + title: Option Value Response + type: object + properties: + data: + title: Option Value + type: object + allOf: + - title: Option Value Base + required: + - label + - sort_order + type: object + properties: + is_default: + type: boolean + description: | + The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. + example: false + label: + type: string + description: | + The text display identifying the value on the storefront. Required in a /POST. + example: Green + x-required: + - post + sort_order: + maximum: 2147483647 + minimum: -2147483648 + type: integer + description: | + The order in which the value will be displayed on the product page. Required in a /POST. + example: 0 + x-required: + - post + value_data: + type: object + properties: {} + description: | + Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. + x-nullable: true + description: Common Option Value properties. + - type: object + properties: + id: + type: integer + description: | + The unique numeric ID of the value; increments sequentially. + meta: + $ref: '#/components/schemas/metaEmpty_Full' + example: + data: + id: 44 + label: Pick a color + sort_order: 9 + value_data: + colors: + - '#123c91, #FFFF00, #397a44' + is_default: false + '404': + description: No option(s) were found with this query. + content: {} + '422': + description: | + The `OptionValue` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + x-codegen-request-body-name: OptionValue + delete: + tags: + - Values + summary: Delete a Product Variant Option Value + description: Deletes a *Variant Option Value*. + operationId: deleteOptionValueById + parameters: + - name: option_id + in: path + description: | + The ID of the `Option`. + required: true + schema: + type: integer + - name: value_id + in: path + description: | + The ID of the `Modifier/Option Value`. + required: true + schema: + type: integer + responses: + '204': + description: '' + content: {} + parameters: + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/ProductIdParam' + - $ref: '#/components/parameters/OptionIdParam' + - $ref: '#/components/parameters/ValueIdParam' +components: + schemas: + productOption_Base: + title: productOption_Base + type: object + properties: + id: + type: integer + description: | + The unique numerical ID of the option, increments sequentially. + nullable: true + example: 55 + product_id: + type: integer + description: | + The unique numerical ID of the product to which the option belongs. + example: 4 + x-required: + - post + - put + display_name: + maxLength: 255 + minLength: 1 + type: string + description: | + The name of the option shown on the storefront. + example: Add-a-$5-Donation1535042499-187 + x-required: + - post + - put + type: + type: string + description: | + The type of option, which determines how it will display on the storefront. Acceptable values: `radio_buttons`, `rectangles`, `dropdown`, `product_list`, `product_list_with_images`, `swatch`. For reference, the former v2 API values are: RB = radio_buttons, RT = rectangles, S = dropdown, P = product_list, PI = product_list_with_images, CS = swatch. + enum: + - radio_buttons + - rectangles + - dropdown + - product_list + - product_list_with_images + - swatch + x-required: + - post + - put + config: + $ref: '#/components/schemas/productOptionConfig_Full' + sort_order: + type: integer + description: 'Order in which the option is displayed on the storefront. ' + example: 1 + option_values: + type: array + items: + $ref: '#/components/schemas/productOptionOptionValue_Full' + description: Common Option properties. + x-internal: false + productOption_Full: + title: productOption_Full + allOf: + - $ref: '#/components/schemas/productOption_Base' + - type: object + properties: + name: + type: string + description: | + The unique option name, auto-generated from the display name, a timestamp, and the product ID. + example: Add-a-$5-Donation1535042499-187 + x-internal: false + productOptionOptionValue_Base: + title: productOptionOptionValue_Base + required: + - label + - sort_order + type: object + properties: + is_default: + type: boolean + description: | + The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. + example: false + label: + type: string + description: | + The text display identifying the value on the storefront. Required in a /POST. + example: Green + x-required: + - post + sort_order: + maximum: 2147483647 + minimum: -2147483648 + type: integer + description: | + The order in which the value will be displayed on the product page. Required in a /POST. + example: 0 + x-required: + - post + value_data: + type: object + properties: {} + description: | + Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. If no data is available, returns `null`. + nullable: true + description: Common Product Option `option_value` properties. + x-internal: false + productOptionOptionValue_Full: + title: productOptionOptionValue_Full + description: Product Option `option_value`. + allOf: + - $ref: '#/components/schemas/productOptionOptionValue_Base' + - type: object + properties: + id: + type: integer + description: | + The unique numeric ID of the value; increments sequentially. + x-internal: false + productOptionConfig_Full: + title: productOptionConfig_Full + type: object + properties: + default_value: + type: string + description: | + (date, text, multi_line_text, numbers_only_text) The default value. Shown on a date option as an ISO-8601–formatted string, or on a text option as a string. + checked_by_default: + type: boolean + description: | + (checkbox) Flag for setting the checkbox to be checked by default. + checkbox_label: + type: string + description: | + (checkbox) Label displayed for the checkbox option. + date_limited: + type: boolean + description: | + (date) Flag to limit the dates allowed to be entered on a date option. + date_limit_mode: + type: string + description: | + (date) The type of limit that is allowed to be entered on a date option. + example: range + enum: + - earliest + - range + - latest + date_earliest_value: + type: string + description: | + (date) The earliest date allowed to be entered on the date option, as an ISO-8601 formatted string. + format: date + date_latest_value: + type: string + description: | + (date) The latest date allowed to be entered on the date option, as an ISO-8601 formatted string. + format: date + file_types_mode: + type: string + description: | + (file) The kind of restriction on the file types that can be uploaded with a file upload option. Values: `specific` - restricts uploads to particular file types; `all` - allows all file types. + example: specific + enum: + - specific + - all + file_types_supported: + type: array + description: | + (file) The type of files allowed to be uploaded if the `file_type_option` is set to `specific`. Values: + `images` - Allows upload of image MIME types (`bmp`, `gif`, `jpg`, `jpeg`, `jpe`, `jif`, `jfif`, `jfi`, `png`, `wbmp`, `xbm`, `tiff`). `documents` - Allows upload of document MIME types (`txt`, `pdf`, `rtf`, `doc`, `docx`, `xls`, `xlsx`, `accdb`, `mdb`, `one`, `pps`, `ppsx`, `ppt`, `pptx`, `pub`, `odt`, `ods`, `odp`, `odg`, `odf`). + `other` - Allows file types defined in the `file_types_other` array. + items: + type: string + example: 'images, documents, other' + file_types_other: + type: array + description: | + (file) A list of other file types allowed with the file upload option. + items: + type: string + example: pdf + file_max_size: + type: integer + description: | + (file) The maximum size for a file that can be used with the file upload option. This will still be limited by the server. + example: 5 + text_characters_limited: + type: boolean + description: | + (text, multi_line_text) Flag to validate the length of a text or multi-line text input. + text_min_length: + type: integer + description: | + (text, multi_line_text) The minimum length allowed for a text or multi-line text option. + example: 1 + text_max_length: + type: integer + description: | + (text, multi_line_text) The maximum length allowed for a text or multi line text option. + example: 55 + text_lines_limited: + type: boolean + description: | + (multi_line_text) Flag to validate the maximum number of lines allowed on a multi-line text input. + example: true + text_max_lines: + type: integer + description: | + (multi_line_text) The maximum number of lines allowed on a multi-line text input. + example: 4 + number_limited: + type: boolean + description: | + (numbers_only_text) Flag to limit the value of a number option. + example: true + number_limit_mode: + type: string + description: | + (numbers_only_text) The type of limit on values entered for a number option. + example: lowest + enum: + - lowest + - highest + - range + number_lowest_value: + type: number + description: | + (numbers_only_text) The lowest allowed value for a number option if `number_limited` is true. + example: 100 + number_highest_value: + type: number + description: | + (numbers_only_text) The highest allowed value for a number option if `number_limited` is true. + number_integers_only: + type: boolean + description: | + (numbers_only_text) Flag to limit the input on a number option to whole numbers only. + example: false + product_list_adjusts_inventory: + type: boolean + description: | + (product_list, product_list_with_images) Flag for automatically adjusting inventory on a product included in the list. + product_list_adjusts_pricing: + type: boolean + description: | + (product_list, product_list_with_images) Flag to add the optional product's price to the main product's price. + product_list_shipping_calc: + type: string + description: | + (product_list, product_list_with_images) How to factor the optional product's weight and package dimensions into the shipping quote. Values: `none` - don't adjust; `weight` - use shipping weight only; `package` - use weight and dimensions. + example: weight + enum: + - none + - weight + - package + description: The values for option config can vary based on the Modifier created. + x-internal: false + metaCollection_Full: + title: metaCollection_Full + type: object + properties: + pagination: + $ref: '#/components/schemas/pagination_Full' + description: 'Data about the response, including pagination and collection totals.' + x-internal: false + pagination_Full: + title: pagination_Full + type: object + properties: + total: + type: integer + description: | + Total number of items in the result set. + example: 36 + count: + type: integer + description: | + Total number of items in the collection response. + example: 36 + per_page: + type: integer + description: | + The amount of items returned in the collection per page, controlled by the limit parameter. + example: 50 + current_page: + type: integer + description: | + The page you are currently on within the collection. + example: 1 + total_pages: + type: integer + description: | + The total number of pages in the collection. + example: 1 + links: + type: object + properties: + previous: + type: string + description: | + Link to the previous page returned in the response. + current: + type: string + description: | + Link to the current page returned in the response. + example: '?page=1&limit=50' + next: + type: string + description: | + Link to the next page returned in the response. + description: | + Pagination links for the previous and next parts of the whole collection. + description: 'Data about the response, including pagination and collection totals.' + x-internal: false + metaEmpty_Full: + type: object + title: Response meta + properties: {} + additionalProperties: true + description: Response metadata. + parameters: + ProductIdParam: + name: product_id + in: path + description: | + The ID of the `Product` to which the resource belongs. + required: true + schema: + type: integer + ValueIdParam: + name: value_id + description: | + The ID of the `Modifier/Option Value`. + required: true + in: path + schema: + type: integer + OptionIdParam: + name: option_id + description: | + The ID of the `Option`. + required: true + in: path + schema: + type: integer + Accept: + name: Accept + in: header + required: true + description: 'The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body.' + schema: + type: string + default: 'application/json' + ContentType: + name: Content-Type + in: header + required: true + description: 'The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the request body.' + schema: + type: string + default: 'application/json' + securitySchemes: + X-Auth-Token: + name: X-Auth-Token + description: |- + ### OAuth scopes + + | UI Name | Permission | Parameter | + |:--------|:-----------|:----------| + | Products | modify | `store_v2_products` | + | Products | read-only | `store_v2_products_read_only` | + + ### Authentication header + + | Header | Argument | Description | + |:-------|:---------|:------------| + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | + + ### Further reading + + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). + + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). + + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). + type: apiKey + in: header diff --git a/reference/catalog/product-variants_catalog.v3.yml b/reference/catalog/product-variants_catalog.v3.yml new file mode 100644 index 000000000..a6d88e506 --- /dev/null +++ b/reference/catalog/product-variants_catalog.v3.yml @@ -0,0 +1,2429 @@ +openapi: '3.0.3' +info: + title: Catalog - Product Variants + description: |- + > The Catalog API manages products, categories, brands, bulk pricing rules, and more. To learn more about catalog resources, see the [Catalog Overview](/docs/store-operations/catalog). + + A Product Variant is a version of a product that has its own SKU. For example, a catalog might model a particular style of high-top sneakers that come in both red and blue as one product - high-tops - with two variants - red and blue. From a storefront point of view, Product Variants are often what shoppers seek. They are also the object that maps to SKUs and tracks inventory. A Product with one only Variant is a _base variant_. + + Our Catalog Product Variants endpoints let you work in two ways. + + On a per-product basis, you can [create and manage Product Variants](/docs/rest-catalog/product-variants), their [images](/docs/rest-catalog/product-variants/images), and their [metafields](/docs/rest-catalog/product-variants/metafields), which are arbitrary key-value attributes. + + By design, Product Variants consist of a combination of [Product Variant Option values](/docs/rest-catalog/product-variant-options/values). + + This API family also provides endpoints that can make [batch updates](/docs/rest-catalog/product-variants/variants-batch#update-variants-batch) to Product Variants from different products across the Catalog, as well as [getting all variants](/docs/rest-catalog/product-variants/variants-batch#get-all-variants). + + The terms "product variant" and "variant" are used interchangeably throughout the documentation. + + > To learn more about authenticating Catalog endpoints, locate the **Authentication** section at the top of each endpoint, then click **Show Details**. + + ## Resources + + ### Webhooks + Learn more about [Product webhook events](/docs/integrations/webhooks/events#products). + + ### Additional Catalog endpoints + * [Brands](/docs/rest-catalog/brands) + * [Categories](/docs/rest-catalog/categories) + * [Category Trees](/docs/rest-catalog/category-trees) + * [Products](/docs/rest-catalog/products) + * [Product Modifiers](/docs/rest-catalog/product-modifiers) + * [Product Variant Options](/docs/rest-catalog/product-variant-options) + + termsOfService: 'https://www.bigcommerce.com/terms' + contact: + name: BigCommerce + url: 'https://www.bigcommerce.com' + email: support@bigcommerce.com + version: '' +servers: + - url: 'https://api.bigcommerce.com/stores/{store_hash}/v3' + variables: + store_hash: + default: store_hash + description: Permanent ID of the BigCommerce store. + description: BigCommerce API Gateway +security: + - X-Auth-Token: [] +tags: + - name: Product Variants + - name: Variants (Batch) + - name: Metafields + - name: Images +paths: + '/catalog/products/{product_id}/variants': + get: + tags: + - Product Variants + summary: Get All Product Variants + description: Returns a list of product *Variants*. Optional parameters can be passed in. + operationId: getVariantsByProductId + parameters: + - name: page + in: query + description: Specifies the page number in a limited (paginated) list of products. + schema: + type: integer + - name: limit + in: query + description: Controls the number of items per page in a limited (paginated) list of products. + schema: + type: integer + - name: include_fields + in: query + description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' + schema: + type: string + - name: exclude_fields + in: query + description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + title: Variant Collection Response + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/productVariant_Full' + meta: + $ref: '#/components/schemas/metaCollection_Full' + example: + data: + - id: 382 + product_id: 192 + sku: SMIT + sku_id: 348 + price: 10 + calculated_price: 10 + sale_price: 8 + retail_price: 10 + map_price: {} + weight: 4 + calculated_weight: 2 + width: 5 + height: 5 + depth: 5 + is_free_shipping: false + fixed_cost_shipping_price: 10 + purchasing_disabled: false + purchasing_disabled_message: '' + image_url: '' + cost_price: 0 + upc: '' + mpn: '' + gtin: '' + inventory_level: 0 + inventory_warning_level: 0 + bin_picking_number: '' + option_values: + - id: 174 + label: Beige + option_id: 220 + option_display_name: Color + - id: 383 + product_id: 192 + sku: SMIT-1 + sku_id: 349 + price: 25 + calculated_price: 25 + sale_price: 20 + retail_price: 25 + map_price: {} + weight: 2 + calculated_weight: 1 + width: 5 + height: 5 + depth: 5 + is_free_shipping: false + fixed_cost_shipping_price: 10 + purchasing_disabled: false + purchasing_disabled_message: '' + image_url: '' + cost_price: 25 + upc: '' + mpn: '' + gtin: '' + inventory_level: 0 + inventory_warning_level: 0 + bin_picking_number: '' + option_values: + - id: 175 + label: Grey + option_id: 220 + option_display_name: Color + - id: 384 + product_id: 192 + sku: SMIT-2 + sku_id: 350 + price: 25 + calculated_price: 25 + sale_price: 20 + retail_price: 25 + map_price: {} + weight: 2 + calculated_weight: 1 + width: 5 + height: 5 + depth: 5 + is_free_shipping: false + fixed_cost_shipping_price: 10 + purchasing_disabled: false + purchasing_disabled_message: '' + image_url: '' + cost_price: 25 + upc: '' + mpn: '' + gtin: '' + inventory_level: 0 + inventory_warning_level: 0 + bin_picking_number: '' + option_values: + - id: 176 + label: Black + option_id: 220 + option_display_name: Color + meta: + pagination: + total: 3 + count: 3 + per_page: 50 + current_page: 1 + total_pages: 1 + links: + current: '?page=1&limit=50' + '404': + description: | + The resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + post: + tags: + - Product Variants + summary: Create a Product Variant + description: |- + Creates a *Product Variant*. + + **Required Fields** + * sku + * option_values + + **Read-Only Fields** + * id + + **Limits** + * 600 SKUs per product limit. + * 255 characters SKU length limit. + + Variants need to be created one at a time using this endpoint. To use a variant array and create products and variants in the same call use the [Create Products](/docs/rest-catalog/products#create-a-product) during the initial product creation. + operationId: createVariant + parameters: + - $ref: '#/components/parameters/ContentType' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/productVariant_Post' + required: true + responses: + '200': + description: '' + content: + application/json: + schema: + title: Variant Response + type: object + properties: + data: + $ref: '#/components/schemas/productVariant_Full' + meta: + $ref: '#/components/schemas/metaEmpty_Full' + examples: + example-1: + value: + data: + cost_price: 0 + price: 0 + sale_price: 0 + retail_price: 0 + weight: 0 + width: 0 + height: 0 + depth: 0 + is_free_shipping: true + fixed_cost_shipping_price: 0 + purchasing_disabled: true + purchasing_disabled_message: string + upc: string + inventory_level: 0 + inventory_warning_level: 0 + bin_picking_number: string + mpn: string + gtin: '012345678905' + id: 0 + product_id: 0 + sku: string + sku_id: 0 + option_values: + - option_display_name: Color + label: Beige + id: 146 + option_id: 151 + calculated_price: 0 + calculated_weight: 0 + meta: {} + example-2: + value: + data: + id: 384 + product_id: 192 + sku: SMIT-2 + sku_id: 350 + price: 25 + calculated_price: 25 + sale_price: 20 + retail_price: 25 + map_price: {} + weight: 2 + calculated_weight: 1 + width: 5 + height: 5 + depth: 5 + is_free_shipping: false + fixed_cost_shipping_price: 10 + purchasing_disabled: false + purchasing_disabled_message: '' + image_url: '' + cost_price: 25 + upc: '' + mpn: '' + gtin: '' + inventory_level: 0 + inventory_warning_level: 0 + bin_picking_number: '' + option_values: + - id: 176 + label: Black + option_id: 220 + option_display_name: Color + meta: {} + '207': + description: |- + Multi-status. The product information was updated successfully, but the inventory data failed to update. + + Verify that the inventory-related updates are well-formed and correct; for example, that they donʼt result in negative stock levels. Then consider updating the inventory data again. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/productVariant_Full' + errors: + $ref: '#/components/schemas/errorMultiStatus' + meta: + $ref: '#/components/schemas/metaCollection_Full' + '404': + description: | + The resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + x-codegen-request-body-name: Variant + parameters: + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/ProductIdParam' + '/catalog/products/{product_id}/variants/{variant_id}': + get: + tags: + - Product Variants + summary: Get a Product Variant + description: Returns a single product *Variant*. Optional parameters can be passed in. + operationId: getVariantById + parameters: + - name: include_fields + in: query + description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' + schema: + type: string + - name: exclude_fields + in: query + description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + title: Variant Response + type: object + properties: + data: + $ref: '#/components/schemas/productVariant_Full' + meta: + $ref: '#/components/schemas/metaEmpty_Full' + example: + data: + id: 384 + product_id: 192 + sku: SMIT-2 + sku_id: 350 + price: 25 + calculated_price: 25 + sale_price: 20 + retail_price: 25 + map_price: {} + weight: 2 + calculated_weight: 1 + width: 5 + height: 5 + depth: 5 + is_free_shipping: false + fixed_cost_shipping_price: 10 + purchasing_disabled: false + purchasing_disabled_message: '' + image_url: '' + cost_price: 25 + upc: '' + mpn: '' + gtin: '' + inventory_level: 0 + inventory_warning_level: 0 + bin_picking_number: '' + option_values: + - id: 176 + label: Black + option_id: 220 + option_display_name: Color + meta: {} + '404': + description: | + The resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + put: + tags: + - Product Variants + summary: Update a Product Variant + description: Updates a product *Variant*. + operationId: updateVariant + parameters: + - $ref: '#/components/parameters/ContentType' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/productVariant_Put' + required: true + responses: + '200': + description: '' + content: + application/json: + schema: + title: Variant Response + type: object + properties: + data: + $ref: '#/components/schemas/productVariant_Full' + meta: + $ref: '#/components/schemas/metaEmpty_Full' + example: + data: + bin_picking_number: '0' + calculated_price: 85 + calculated_weight: 1 + cost_price: 0 + depth: 22 + fixed_cost_shipping_price: 0 + gtin: '' + height: 14.6 + id: 65 + inventory_level: 0 + inventory_warning_level: 0 + is_free_shipping: false + map_price: 0 + mpn: TR-SML02 + option_values: [] + price: 89 + product_id: 81 + purchasing_disabled: true + purchasing_disabled_message: This item is not available. + retail_price: 89 + sale_price: 85 + sku: OTS + sku_id: 10 + upc: '' + weight: 1 + width: 2 + meta: {} + '207': + description: |- + Multi-status. The product information was updated successfully, but the inventory data failed to update. + + Verify that the inventory-related updates are well-formed and correct; for example, that they donʼt result in negative stock levels. Then consider updating the inventory data again. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/productVariant_Full' + errors: + $ref: '#/components/schemas/errorMultiStatus' + meta: + $ref: '#/components/schemas/metaCollection_Full' + '404': + description: | + The resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + x-codegen-request-body-name: Variant + delete: + tags: + - Product Variants + summary: Delete a Product Variant + description: Deletes a product *Variant*. + operationId: deleteVariantById + responses: + '204': + description: '' + content: {} + parameters: + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/ProductIdParam' + - $ref: '#/components/parameters/VariantIdParam' + '/catalog/products/{product_id}/variants/{variant_id}/metafields': + get: + tags: + - Metafields + summary: Get All Product Variant Metafields + description: Returns a list of product variant *Metafields*. Optional parameters can be passed in. + operationId: getVariantMetafieldsByProductIdAndVariantId + parameters: + - name: variant_id + in: path + description: | + ID of the variant on a product, or on an associated Price List Record. + required: true + schema: + type: integer + + - name: page + in: query + description: Specifies the page number in a limited (paginated) list of products. + schema: + type: integer + - name: limit + in: query + description: Controls the number of items per page in a limited (paginated) list of products. + schema: + type: integer + - name: key + in: query + description: | + Filter based on a metafield's key. + schema: + type: string + - name: namespace + in: query + description: Filter based on a metafield's namespace. + schema: + type: string + - name: include_fields + in: query + description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' + schema: + type: string + - name: exclude_fields + in: query + description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + title: Meta Field Collection Response + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/metafield_Full' + meta: + $ref: '#/components/schemas/categoriesTree_Resp' + '404': + description: | + The resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + post: + tags: + - Metafields + summary: Create a Product Variant Metafield + description: |- + Creates a product variant *Metafield*. + + **Required Fields:** + * permission_set + * namespace + * key + * value + + **Read-Only Fields** + * id + + **Note:** The maxiumum number of metafields allowed on each order, product, category, variant, or brand is 250 per client ID. For more information, see [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center. + operationId: createVariantMetafield + parameters: + - $ref: '#/components/parameters/ContentType' + - name: variant_id + in: path + description: | + ID of the variant on a product, or on an associated Price List Record. + required: true + schema: + type: integer + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/metafield_Base' + required: true + responses: + '200': + description: '' + content: + application/json: + schema: + title: Metafield Response + type: object + properties: + data: + $ref: '#/components/schemas/metafield_Full' + meta: + $ref: '#/components/schemas/metaEmpty_Full' + example: + data: + id: 4 + key: location_id + value: 'Shelf 3, Bin 5' + namespace: App Namespace + permission_set: app_only + resource_type: variant + resource_id: 137 + description: Where products are located + date_created: '2021-08-06T19:15:35+00:00' + date_modified: '2021-08-06T19:15:35+00:00' + meta: {} + '409': + description: | + The `Metafield` was in conflict with another `Metafield`. This can be the result of duplicate unique-key combinations of the app's client id, namespace, key, resource_type, and resource_id. + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + '422': + description: | + The `Metafield` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + x-codegen-request-body-name: Metafield + parameters: + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/ProductIdParam' + - $ref: '#/components/parameters/VariantIdParam' + '/catalog/products/{product_id}/variants/{variant_id}/metafields/{metafield_id}': + get: + tags: + - Metafields + summary: Get a Product Variant Metafields + description: Returns a single product variant *Metafield*. Optional parameters can be passed in. + operationId: getVariantMetafieldByProductIdAndVariantId + parameters: + - name: include_fields + in: query + description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' + schema: + type: string + - name: exclude_fields + in: query + description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + title: Metafield Response + type: object + properties: + data: + $ref: '#/components/schemas/metafield_Full' + meta: + $ref: '#/components/schemas/metaEmpty_Full' + example: + data: + id: 8 + key: location_id + value: 'Shelf 3, Bin 5' + namespace: Inventory Namespace + permission_set: read + resource_type: variant + resource_id: 158 + description: Where products are located + date_created: '2018-09-13T16:42:37+00:00' + date_modified: '2018-09-13T16:42:37+00:00' + meta: {} + '404': + description: | + The resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + put: + tags: + - Metafields + summary: Update Product Variant Metafields + description: "Updates a product variant *Metafield*.\n\n**Required Fields:**\n* none\n\n**Read-Only Fields**\n* id\n* These fields can only be modified by the app (API credentials) that created the metafield:\n\t* namespace\n\t* key\n\t* permission_set\n\n**Usage Notes**\n* Attempting to modify `namespace`, `key`, and `permission_set` fields using a client ID different from the one used to create those metafields will result in a 403 error message. " + operationId: updateVariantMetafield + parameters: + - $ref: '#/components/parameters/ContentType' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/metafield_Base' + required: true + responses: + '200': + description: '' + content: + application/json: + schema: + title: Metafield Response + type: object + properties: + data: + $ref: '#/components/schemas/metafield_Full' + meta: + $ref: '#/components/schemas/metaEmpty_Full' + example: + data: + id: 8 + key: location_id + value: 'Shelf 3, Bin 5' + namespace: Inventory Namespace + permission_set: read + resource_type: variant + resource_id: 158 + description: Where products are located + date_created: '2018-09-13T16:42:37+00:00' + date_modified: '2018-09-13T16:42:37+00:00' + meta: {} + '404': + description: | + The resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + x-codegen-request-body-name: Metafield + delete: + tags: + - Metafields + summary: Delete a Variant Metafield + description: Deletes a product variant *Metafield*. + operationId: deleteVariantMetafieldById + responses: + '204': + description: '' + content: {} + parameters: + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/ProductIdParam' + - $ref: '#/components/parameters/VariantIdParam' + - $ref: '#/components/parameters/MetafieldIdParam' + '/catalog/products/{product_id}/variants/{variant_id}/image': + post: + tags: + - Images + summary: Create a Variant Image + description: |- + Creates a *Variant Image*. + + Only one image can be explicitly associated with a Variant. If the Variant already has an associated image, overwrites the existing Variant Image. + + The image displays on the storefront when the Variant is selected. + + **Required Fields** + - image_file: Form posts. Files larger than 1 MB are not accepted + - image_url: Any publicly available URL + operationId: createVariantImage + parameters: + - $ref: '#/components/parameters/ContentType' + - name: variant_id + in: path + description: | + ID of the variant on a product, or on an associated Price List Record. + required: true + schema: + type: integer + requestBody: + content: + application/json: + schema: + type: object + properties: + image_url: + type: string + description: | + A public URL for a GIF, JPEG, or PNG image. Limit of 8MB per file. + description: 'An object containing a publicly accessible image URL, or a form post that contains an image file.' + multipart/form-data: + schema: + type: object + properties: + image_url: + type: string + description: | + A public URL for a GIF, JPEG, or PNG image. Limit of 8MB per file. + description: 'An object containing a publicly accessible image URL, or a form post that contains an image file.' + required: false + responses: + '200': + description: '`image_url` is returned for both `image_file` and `image_url`.' + content: + application/json: + schema: + title: Image Response + type: object + properties: + data: + title: Resource Image + type: object + properties: + image_url: + type: string + description: | + A public URL for a GIF, JPEG, or PNG image. Limit of 8MB per file. + description: 'An object containing a publicly accessible image URL, or a form post that contains an image file.' + meta: + $ref: '#/components/schemas/metaEmpty_Full' + description: |- + Image Response returns for: + * Create Variant Image + * Create Modifier Image + * Create Category Image + * Create Brand Image + example: + data: + image_url: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/product_images/attribute_rule_images/85_source_1536863430.png' + meta: {} + '400': + description: Bad Request. The requested resource could not be downloaded and may be invalid. Possible reasons include malformed request syntax or the file host blocking requests. + content: + application/json: + schema: + type: object + properties: {} + '404': + description: | + The resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + '422': + description: | + Image was not valid. This is the result of a missing `image_file` field or of an incorrect file type. See the response for more details. + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + '500': + description: Returns for an `image_file` larger than 1 MB. + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + x-codegen-request-body-name: body + parameters: + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/ProductIdParam' + - $ref: '#/components/parameters/VariantIdParam' + '/catalog/variants': + get: + tags: + - Variants (Batch) + summary: Get All Variants + description: Returns a list of all variants in your catalog. Optional parameters can be passed in. + operationId: getVariants + parameters: + - name: id + in: query + description: Filter items by ID. + schema: + type: integer + - name: sku + in: query + description: Filter items by SKU. + schema: + type: string + - name: upc + in: query + description: Filter items by UPC. + schema: + type: string + - name: page + in: query + description: Specifies the page number in a limited (paginated) list of products. + schema: + type: integer + - name: limit + in: query + description: Controls the number of items per page in a limited (paginated) list of products. + schema: + type: integer + - name: include_fields + in: query + description: Fields to include, in a comma-separated list. The ID and the specified fields will be returned. + schema: + type: string + - name: exclude_fields + in: query + description: Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded. + schema: + type: string + - name: product_id + in: query + description: |- + A comma-separated list of IDs of products whose variants were requested. For example:`?product_id:in=77,80,81` + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + title: Variant Collection Response + type: object + properties: + data: + type: array + items: + type: object + allOf: + - title: Variant Base + type: object + properties: + cost_price: + minimum: 0 + type: number + description: The cost price of the variant. Not affected by Price List prices. + format: double + x-nullable: true + price: + minimum: 0 + type: number + description: 'This variant’s base price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is `null`, the product’s default price (set in the Product resource’s `price` field) will be used as the base price.' + format: double + x-nullable: true + sale_price: + minimum: 0 + type: number + description: 'This variant’s sale price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s sale price (set in the Product resource’s `price` field) will be used as the sale price.' + format: double + x-nullable: true + retail_price: + minimum: 0 + type: number + description: 'This variant’s retail price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s retail price (set in the Product resource’s `price` field) will be used as the retail price.' + format: double + x-nullable: true + weight: + minimum: 0 + type: number + description: 'This variant’s base weight on the storefront. If this value is null, the product’s default weight (set in the Product resource’s weight field) will be used as the base weight.' + format: double + x-nullable: true + width: + minimum: 0 + type: number + description: | + Width of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default width (set in the Product resource's `width` field) will be used as the base width. + format: double + x-nullable: true + height: + minimum: 0 + type: number + description: | + Height of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default height (set in the Product resource's `height` field) will be used as the base height. + format: double + x-nullable: true + depth: + minimum: 0 + type: number + description: | + Depth of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default depth (set in the Product resource's `depth` field) will be used as the base depth. + format: double + x-nullable: true + is_free_shipping: + type: boolean + description: | + Flag used to indicate whether the variant has free shipping. If `true`, the shipping cost for the variant will be zero. + fixed_cost_shipping_price: + minimum: 0 + type: number + description: | + A fixed shipping cost for the variant. If defined, this value will be used during checkout instead of normal shipping-cost calculation. + format: double + x-nullable: true + purchasing_disabled: + type: boolean + description: 'If `true`, this variant will not be purchasable on the storefront.' + purchasing_disabled_message: + maxLength: 255 + minLength: 0 + type: string + description: 'If `purchasing_disabled` is `true`, this message should show on the storefront when the variant is selected.' + upc: + type: string + description: The UPC code used in feeds for shopping comparison sites and external channel integrations. + x-nullable: true + inventory_level: + type: integer + description: |- + Inventory level for the variant, which is used when the product’s inventory_tracking is set to `variant`. The Catalog API returns the inventory for only the default location. + + The inventory for a variant cannot exceed 2,147,483,647 in the catalog. The sum of the variant inventories, or the total inventory for a product, cannot exceed 2,147,483,647. + + If you exceed the limit, the store sets the variant inventory to the limit if no other variant inventories are set. If other variant inventories are set, the store does not save the variant inventory rather than setting the variant inventory to the remaining limit. + + The Catalog API handles limits in a different way than the Inventory API. For more information, see [Limit handling](/docs/store-operations/catalog/inventory-adjustments#limit-handling-in-inventory-versus-catalog-api). + x-nullable: true + maximum: 2147483647 + inventory_warning_level: + type: integer + description: 'When the variant hits this inventory level, it is considered low stock.' + x-nullable: true + maximum: 2147483647 + bin_picking_number: + maxLength: 255 + minLength: 0 + type: string + description: Identifies where in a warehouse the variant is located. + x-nullable: true + description: Common Variant properties. + - type: object + properties: + id: + type: integer + product_id: + type: integer + sku: + type: string + sku_id: + type: integer + description: Read-only reference to v2 API's SKU ID. Null if it is a base variant. + x-nullable: true + option_values: + type: array + description: Array of option and option values IDs that make up this variant. Will be empty if the variant is the product's base variant. + items: + title: Option Value Variant + type: object + allOf: + - title: Option Value Product Base + type: object + properties: + option_display_name: + maxLength: 255 + minLength: 1 + type: string + description: | + The name of the option. + example: Color + x-required: + - post + label: + maxLength: 255 + minLength: 1 + type: string + description: | + The label of the option value. + example: Beige + x-required: + - post + description: Common Option Value Product properties. + - type: object + properties: + id: + type: integer + option_id: + type: integer + calculated_price: + type: number + description: | + The price of the variant as seen on the storefront. This price takes into account `sale_price` and any price adjustment rules that are applicable to this variant. + format: double + meta: + $ref: '#/components/schemas/metaCollection_Full' + '404': + description: The resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + put: + tags: + - Variants (Batch) + summary: Update Variants (Batch) + description: |- + Updates a batch of `variant` objects. Currently the limit is 50 variants however this is subject to change. + + **Required Fields** + + To update an existing variant: + * id (variant id) + + To create a new variant: + * product_id + * sku + * option_values + - id (option_value ID - Example: 146) + - option_id (Option ID - Example: 151) + + operationId: updateVariantsBatch + parameters: + - $ref: '#/components/parameters/ContentType' + requestBody: + content: + application/json: + schema: + title: Variants Collection Put + type: array + items: + title: Variant Put + type: object + description: | + The model for a PUT to update variants on a product. + allOf: + - title: Variant Base + type: object + properties: + cost_price: + minimum: 0 + type: number + description: The cost price of the variant. Not affected by Price List prices. + format: double + x-nullable: true + example: 40 + price: + minimum: 0 + type: number + description: 'This variant’s base price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is `null`, the product’s default price (set in the Product resource’s `price` field) will be used as the base price.' + format: double + x-nullable: true + example: 40 + sale_price: + minimum: 0 + type: number + description: 'This variant’s sale price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s sale price (set in the Product resource’s `price` field) will be used as the sale price.' + format: double + x-nullable: true + example: 40 + retail_price: + minimum: 0 + type: number + description: 'This variant’s retail price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s retail price (set in the Product resource’s `price` field) will be used as the retail price.' + format: double + x-nullable: true + example: 40 + weight: + minimum: 0 + type: number + description: 'This variant’s base weight on the storefront. If this value is null, the product’s default weight (set in the Product resource’s weight field) will be used as the base weight.' + format: double + x-nullable: true + example: 5 + width: + minimum: 0 + type: number + description: | + Width of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default width (set in the Product resource's `width` field) will be used as the base width. + format: double + x-nullable: true + example: 5 + height: + minimum: 0 + type: number + description: | + Height of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default height (set in the Product resource's `height` field) will be used as the base height. + format: double + x-nullable: true + example: 5 + depth: + minimum: 0 + type: number + description: | + Depth of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default depth (set in the Product resource's `depth` field) will be used as the base depth. + format: double + x-nullable: true + example: 5 + is_free_shipping: + type: boolean + description: | + Flag used to indicate whether the variant has free shipping. If `true`, the shipping cost for the variant will be zero. + fixed_cost_shipping_price: + minimum: 0 + type: number + description: | + A fixed shipping cost for the variant. If defined, this value will be used during checkout instead of normal shipping-cost calculation. + format: double + x-nullable: true + purchasing_disabled: + type: boolean + description: 'If `true`, this variant will not be purchasable on the storefront.' + purchasing_disabled_message: + maxLength: 255 + minLength: 0 + type: string + description: 'If `purchasing_disabled` is `true`, this message should show on the storefront when the variant is selected.' + upc: + type: string + description: The UPC code used in feeds for shopping comparison sites and external channel integrations. + x-nullable: true + example: "1234" + inventory_level: + type: integer + description: |- + Inventory level for the variant, which is used when the product’s inventory_tracking is set to `variant`. The Catalog API returns the inventory for only the default location. + + The inventory for a variant cannot exceed 2,147,483,647 in the catalog. The sum of the variant inventories, or the total inventory for a product, cannot exceed 2,147,483,647. + + If you exceed the limit, the store sets the variant inventory to the limit if no other variant inventories are set. If other variant inventories are set, the store does not save the variant inventory rather than setting the variant inventory to the remaining limit. + + The Catalog API handles limits in a different way than the Inventory API. For more information, see [Limit handling](/docs/store-operations/catalog/inventory-adjustments#limit-handling-in-inventory-versus-catalog-api). + x-nullable: true + maximum: 2147483647 + example: 21474 + inventory_warning_level: + type: integer + description: 'When the variant hits this inventory level, it is considered low stock.' + x-nullable: true + maximum: 2147483647 + example: 5474 + bin_picking_number: + maxLength: 255 + minLength: 0 + type: string + description: Identifies where in a warehouse the variant is located. + x-nullable: true + description: Common Variant properties. + - type: object + properties: + id: + type: integer + example: 154 + x-required: + - put + required: true + responses: + '200': + description: '' + content: + application/json: + schema: + title: Variant Collection Response + type: object + properties: + data: + type: array + items: + type: object + allOf: + - title: Variant Base + type: object + properties: + cost_price: + minimum: 0 + type: number + description: The cost price of the variant. Not affected by Price List prices. + format: double + x-nullable: true + price: + minimum: 0 + type: number + description: 'This variant’s base price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is `null`, the product’s default price (set in the Product resource’s `price` field) will be used as the base price.' + format: double + x-nullable: true + sale_price: + minimum: 0 + type: number + description: 'This variant’s sale price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s sale price (set in the Product resource’s `price` field) will be used as the sale price.' + format: double + x-nullable: true + retail_price: + minimum: 0 + type: number + description: 'This variant’s retail price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s retail price (set in the Product resource’s `price` field) will be used as the retail price.' + format: double + x-nullable: true + weight: + minimum: 0 + type: number + description: 'This variant’s base weight on the storefront. If this value is null, the product’s default weight (set in the Product resource’s weight field) will be used as the base weight.' + format: double + x-nullable: true + width: + minimum: 0 + type: number + description: | + Width of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default width (set in the Product resource's `width` field) will be used as the base width. + format: double + x-nullable: true + height: + minimum: 0 + type: number + description: | + Height of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default height (set in the Product resource's `height` field) will be used as the base height. + format: double + x-nullable: true + depth: + minimum: 0 + type: number + description: | + Depth of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default depth (set in the Product resource's `depth` field) will be used as the base depth. + format: double + x-nullable: true + is_free_shipping: + type: boolean + description: | + Flag used to indicate whether the variant has free shipping. If `true`, the shipping cost for the variant will be zero. + fixed_cost_shipping_price: + minimum: 0 + type: number + description: | + A fixed shipping cost for the variant. If defined, this value will be used during checkout instead of normal shipping-cost calculation. + format: double + x-nullable: true + purchasing_disabled: + type: boolean + description: 'If `true`, this variant will not be purchasable on the storefront.' + purchasing_disabled_message: + maxLength: 255 + minLength: 0 + type: string + description: 'If `purchasing_disabled` is `true`, this message should show on the storefront when the variant is selected.' + upc: + type: string + description: The UPC code used in feeds for shopping comparison sites and external channel integrations. + x-nullable: true + inventory_level: + type: integer + description: |- + Inventory level for the variant, which is used when the product’s inventory_tracking is set to `variant`. The Catalog API returns the inventory for only the default location. + + The inventory for a variant cannot exceed 2,147,483,647 in the catalog. The sum of the variant inventories, or the total inventory for a product, cannot exceed 2,147,483,647. + + If you exceed the limit, the store sets the variant inventory to the limit if no other variant inventories are set. If other variant inventories are set, the store does not save the variant inventory rather than setting the variant inventory to the remaining limit. + + The Catalog API handles limits in a different way than the Inventory API. For more information, see [Limit handling](/docs/store-operations/catalog/inventory-adjustments#limit-handling-in-inventory-versus-catalog-api). + x-nullable: true + maximum: 2147483647 + inventory_warning_level: + type: integer + description: 'When the variant hits this inventory level, it is considered low stock.' + x-nullable: true + maximum: 2147483647 + bin_picking_number: + maxLength: 255 + minLength: 0 + type: string + description: Identifies where in a warehouse the variant is located. + x-nullable: true + description: Common Variant properties. + - type: object + properties: + id: + type: integer + product_id: + type: integer + sku: + type: string + sku_id: + type: integer + description: Read-only reference to v2 API's SKU ID. Null if it is a base variant. + x-nullable: true + option_values: + type: array + description: Array of option and option values IDs that make up this variant. Will be empty if the variant is the product's base variant. + items: + title: Option Value Variant + type: object + allOf: + - title: Option Value Product Base + type: object + properties: + option_display_name: + maxLength: 255 + minLength: 1 + type: string + description: | + The name of the option. + example: Color + x-required: + - post + label: + maxLength: 255 + minLength: 1 + type: string + description: | + The label of the option value. + example: Beige + x-required: + - post + description: Common Option Value Product properties. + - type: object + properties: + id: + type: integer + option_id: + type: integer + calculated_price: + type: number + description: | + The price of the variant as seen on the storefront. This price takes into account `sale_price` and any price adjustment rules that are applicable to this variant. + format: double + meta: + title: Collection Meta + type: object + properties: + pagination: + title: Pagination + type: object + properties: + total: + type: integer + description: | + Total number of items in the result set. + example: 36 + count: + type: integer + description: | + Total number of items in the collection response. + example: 36 + per_page: + type: integer + description: | + The amount of items returned in the collection per page, controlled by the limit parameter. + example: 50 + current_page: + type: integer + description: | + The page you are currently on within the collection. + example: 1 + total_pages: + type: integer + description: | + The total number of pages in the collection. + example: 1 + links: + type: object + properties: + previous: + type: string + description: | + Link to the previous page returned in the response. + current: + type: string + description: | + Link to the current page returned in the response. + example: '?page=1&limit=50' + next: + type: string + description: | + Link to the next page returned in the response. + description: | + Pagination links for the previous and next parts of the whole collection. + description: 'Data about the response, including pagination and collection totals.' + description: 'Data about the response, including pagination and collection totals.' + '413': + description: '' + content: + application/json: + example: + errors: {} + status: 413 + title: The request payload is too large. The maximum items allowed in the array is 50 + type: /api-docs/getting-started/api-status-codes + '422': + description: | + This is the result of missing required fields, or of invalid data. See the response for more details. + content: + application/json: + schema: + title: Variants Batch Error Response + type: object + properties: + batch_errors: + type: array + items: + title: Error Response + type: object + allOf: + - title: Base Error + type: object + properties: + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + instance: + type: string + description: | + Error payload for the BigCommerce API. + - type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + description: | + Errors during batch usage for the BigCommerce API. + x-codegen-request-body-name: body + parameters: + - $ref: '#/components/parameters/Accept' +components: + schemas: + categoriesTree_Resp: + title: categoriesTree_Resp + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/categoriesTreeNode_Full' + meta: + $ref: '#/components/schemas/metaEmpty_Full' + description: | + Returns the categories tree, a nested lineage of the categories with parent->child relationship. The Category objects returned are simplified versions of the category objects returned in the rest of this API. + x-internal: false + categoriesTreeNode_Full: + title: categoriesTreeNode_Full + type: object + properties: + id: + type: integer + description: | + The unique numeric ID of the category; increments sequentially. + example: 26 + parent_id: + type: integer + description: | + The unique numeric ID of the category's parent. This field controls where the category sits in the tree of categories that organize the catalog. + example: 25 + name: + type: string + description: | + The name displayed for the category. Name is unique with respect to the category's siblings. + example: Bath + is_visible: + type: boolean + description: | + Flag to determine whether the product should be displayed to customers browsing the store. If `true`, the category will be displayed. If `false`, the category will be hidden from view. + example: true + url: + type: string + description: | + The custom URL for the category on the storefront. + example: /towels/bath-towels/ + description: Used to reflect parent <> child category relationships. Used by Category Tree. + x-internal: false + productVariant_Base: + title: productVariant_Base + type: object + properties: + cost_price: + minimum: 0 + type: number + description: The cost price of the variant. Not affected by Price List prices. + format: double + nullable: true + price: + minimum: 0 + type: number + description: 'This variant’s base price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is `null`, the product’s default price (set in the Product resource’s `price` field) will be used as the base price.' + format: double + nullable: true + sale_price: + minimum: 0 + type: number + description: 'This variant’s sale price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s sale price (set in the Product resource’s `price` field) will be used as the sale price.' + format: double + nullable: true + retail_price: + minimum: 0 + type: number + description: 'This variant’s retail price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s retail price (set in the Product resource’s `price` field) will be used as the retail price.' + format: double + nullable: true + weight: + minimum: 0 + type: number + description: 'This variant’s base weight on the storefront. If this value is null, the product’s default weight (set in the Product resource’s weight field) will be used as the base weight.' + format: double + nullable: true + width: + minimum: 0 + type: number + description: | + Width of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default width (set in the Product resource's `width` field) will be used as the base width. + format: double + nullable: true + height: + minimum: 0 + type: number + description: | + Height of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default height (set in the Product resource's `height` field) will be used as the base height. + format: double + nullable: true + depth: + minimum: 0 + type: number + description: | + Depth of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default depth (set in the Product resource's `depth` field) will be used as the base depth. + format: double + nullable: true + is_free_shipping: + type: boolean + description: | + Flag used to indicate whether the variant has free shipping. If `true`, the shipping cost for the variant will be zero. + fixed_cost_shipping_price: + minimum: 0 + type: number + description: | + A fixed shipping cost for the variant. If defined, this value will be used during checkout instead of normal shipping-cost calculation. + format: double + nullable: true + purchasing_disabled: + type: boolean + description: 'If `true`, this variant will not be purchasable on the storefront.' + purchasing_disabled_message: + maxLength: 255 + minLength: 0 + type: string + description: 'If `purchasing_disabled` is `true`, this message should show on the storefront when the variant is selected.' + upc: + type: string + description: The UPC code used in feeds for shopping comparison sites and external channel integrations. + nullable: true + inventory_level: + type: integer + description: |- + Inventory level for the variant, which is used when the product’s inventory_tracking is set to `variant`. The Catalog API returns the inventory for only the default location. + + The inventory for a variant cannot exceed 2,147,483,647 in the catalog. The sum of the variant inventories, or the total inventory for a product, cannot exceed 2,147,483,647. + + If you exceed the limit, the store sets the variant inventory to the limit if no other variant inventories are set. If other variant inventories are set, the store does not save the variant inventory rather than setting the variant inventory to the remaining limit. + + The Catalog API handles limits in a different way than the Inventory API. For more information, see [Limit handling](/docs/store-operations/catalog/inventory-adjustments#limit-handling-in-inventory-versus-catalog-api). + nullable: true + maximum: 2147483647 + inventory_warning_level: + type: integer + description: 'When the variant hits this inventory level, it is considered low stock.' + nullable: true + maximum: 2147483647 + bin_picking_number: + maxLength: 255 + minLength: 0 + type: string + description: Identifies where in a warehouse the variant is located. + nullable: true + mpn: + type: string + description: The Manufacturer Part Number (MPN) for the variant. + gtin: + type: string + example: '012345678905' + description: Common Variant properties. + x-internal: false + x-examples: + example-1: + cost_price: 0 + price: 0 + sale_price: 0 + retail_price: 0 + weight: 0 + width: 0 + height: 0 + depth: 0 + is_free_shipping: true + fixed_cost_shipping_price: 0 + purchasing_disabled: true + purchasing_disabled_message: string + upc: string + inventory_level: 0 + inventory_warning_level: 0 + bin_picking_number: string + mpn: string + gtin: '012345678905' + productVariant_Full: + title: productVariant_Full + allOf: + - $ref: '#/components/schemas/productVariant_Base' + - type: object + properties: + id: + type: integer + product_id: + type: integer + sku: + type: string + sku_id: + type: integer + description: Read-only reference to v2 API's SKU ID. Null if it is a base variant. + nullable: true + option_values: + type: array + description: Array of option and option values IDs that make up this variant. Will be empty if the variant is the product's base variant. + items: + $ref: '#/components/schemas/productVariantOptionValue_Full' + calculated_price: + type: number + description: | + The price of the variant as seen on the storefront. This price takes into account `sale_price` and any price adjustment rules that are applicable to this variant. + format: double + calculated_weight: + type: number + x-internal: false + description: '' + x-examples: + example-1: + cost_price: 0 + price: 0 + sale_price: 0 + retail_price: 0 + weight: 0 + width: 0 + height: 0 + depth: 0 + is_free_shipping: true + fixed_cost_shipping_price: 0 + purchasing_disabled: true + purchasing_disabled_message: string + upc: string + inventory_level: 0 + inventory_warning_level: 0 + bin_picking_number: string + mpn: string + gtin: '012345678905' + id: 0 + product_id: 0 + sku: string + sku_id: 0 + option_values: + - option_display_name: Color + label: Beige + id: 146 + option_id: 151 + calculated_price: 0 + calculated_weight: 0 + productVariant_Post: + title: productVariant_Post + description: | + The model for a POST to create variants on a product. + allOf: + - title: Variant Base + type: object + properties: + cost_price: + minimum: 0 + type: number + description: The cost price of the variant. Not affected by Price List prices. + format: double + nullable: true + price: + minimum: 0 + type: number + description: 'This variant’s base price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is `null`, the product’s default price (set in the Product resource’s `price` field) will be used as the base price.' + format: double + nullable: true + sale_price: + minimum: 0 + type: number + description: 'This variant’s sale price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s sale price (set in the Product resource’s `price` field) will be used as the sale price.' + format: double + nullable: true + retail_price: + minimum: 0 + type: number + description: 'This variant’s retail price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s retail price (set in the Product resource’s `price` field) will be used as the retail price.' + format: double + nullable: true + weight: + minimum: 0 + type: number + description: 'This variant’s base weight on the storefront. If this value is null, the product’s default weight (set in the Product resource’s weight field) will be used as the base weight.' + format: double + nullable: true + width: + minimum: 0 + type: number + description: | + Width of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default width (set in the Product resource's `width` field) will be used as the base width. + format: double + nullable: true + height: + minimum: 0 + type: number + description: | + Height of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default height (set in the Product resource's `height` field) will be used as the base height. + format: double + nullable: true + depth: + minimum: 0 + type: number + description: | + Depth of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default depth (set in the Product resource's `depth` field) will be used as the base depth. + format: double + nullable: true + is_free_shipping: + type: boolean + description: | + Flag used to indicate whether the variant has free shipping. If `true`, the shipping cost for the variant will be zero. + fixed_cost_shipping_price: + minimum: 0 + type: number + description: | + A fixed shipping cost for the variant. If defined, this value will be used during checkout instead of normal shipping-cost calculation. + format: double + nullable: true + purchasing_disabled: + type: boolean + description: 'If `true`, this variant will not be purchasable on the storefront.' + purchasing_disabled_message: + maxLength: 255 + minLength: 0 + type: string + description: 'If `purchasing_disabled` is `true`, this message should show on the storefront when the variant is selected.' + upc: + type: string + description: The UPC code used in feeds for shopping comparison sites and external channel integrations. + nullable: true + inventory_level: + type: integer + description: |- + Inventory level for the variant, which is used when the product’s inventory_tracking is set to `variant`. The Catalog API returns the inventory for only the default location. + + The inventory for a variant cannot exceed 2,147,483,647 in the catalog. The sum of the variant inventories, or the total inventory for a product, cannot exceed 2,147,483,647. + + If you exceed the limit, the store sets the variant inventory to the limit if no other variant inventories are set. If other variant inventories are set, the store does not save the variant inventory rather than setting the variant inventory to the remaining limit. + + The Catalog API handles limits in a different way than the Inventory API. For more information, see [Limit handling](/docs/store-operations/catalog/inventory-adjustments#limit-handling-in-inventory-versus-catalog-api). + nullable: true + maximum: 2147483647 + inventory_warning_level: + type: integer + description: 'When the variant hits this inventory level, it is considered low stock.' + nullable: true + maximum: 2147483647 + bin_picking_number: + maxLength: 255 + minLength: 0 + type: string + description: Identifies where in a warehouse the variant is located. + nullable: true + image_url: + type: string + description: Publicly available image url + gtin: + type: string + description: Global Trade Item Number + example: '012345678905' + mpn: + type: string + description: Manufacturer Part Number + example: HV-HM02 + description: Common Variant properties. + - type: object + properties: + product_id: + type: integer + x-required: + - post + sku: + maxLength: 255 + minLength: 1 + type: string + x-required: + - post + option_values: + type: array + description: Array of option and option values IDs that make up this variant. Will be empty if the variant is the product's base variant. + items: + $ref: '#/components/schemas/productVariantOptionValue_Full' + x-required: + - post + x-internal: false + productVariantOptionValue_Full: + title: productVariantOptionValue_Full + allOf: + - type: object + properties: + option_display_name: + maxLength: 255 + minLength: 1 + type: string + description: | + The name of the option. + example: Color + x-required: + - post + label: + maxLength: 255 + minLength: 1 + type: string + description: | + The label of the option value. + example: Beige + x-required: + - post + - $ref: '#/components/schemas/productVariantOptionValue_Base' + x-internal: false + productVariantOptionValue_Base: + title: productVariantOptionValue_Base + type: object + properties: + id: + type: integer + description: '`option_value` ID.' + example: 146 + option_id: + type: integer + description: '`option` ID.' + example: 151 + description: Common Product Variant Option properties. + x-internal: false + metafield_Base: + title: metafield_Base + type: object + description: 'Metafield for products, categories, variants, and brands; the max number of metafields allowed on each is 50. For more information, see [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center.' + x-internal: false + properties: + key: + maxLength: 64 + minLength: 1 + type: string + description: | + The name of the field, for example: `location_id`, `color`. Required for POST. + example: Location + x-required: + - post + value: + maxLength: 65535 + minLength: 1 + type: string + description: | + The value of the field, for example: `1`, `blue`. Required for POST. + example: 4HG + x-required: + - post + namespace: + maxLength: 64 + minLength: 1 + type: string + description: | + Namespace for the metafield, for organizational purposes. This is set by the developer. Required for POST. + example: Warehouse Locations + x-required: + - post + permission_set: + type: string + description: |- + Determines the visibility and writeability of the field by other API consumers. + + |Value|Description + |-|-| + |`app_only`|Private to the app that owns the field| + |`read`|Visible to other API consumers| + |`write`|Open for reading and writing by other API consumers| + |`read_and_sf_access`|Visible to other API consumers, including on storefront| + |`write_and_sf_access`|Open for reading and writing by other API consumers, including on storefront| + enum: + - app_only + - read + - write + - read_and_sf_access + - write_and_sf_access + description: + maxLength: 255 + minLength: 1 + type: string + description: | + Description for the metafields. + example: Location in the warehouse + required: + - permission_set + - namespace + - key + - value + metaCollection_Full: + title: metaCollection_Full + type: object + properties: + pagination: + $ref: '#/components/schemas/pagination_Full' + description: 'Data about the response, including pagination and collection totals.' + x-internal: false + pagination_Full: + title: pagination_Full + type: object + properties: + total: + type: integer + description: | + Total number of items in the result set. + example: 36 + count: + type: integer + description: | + Total number of items in the collection response. + example: 36 + per_page: + type: integer + description: | + The amount of items returned in the collection per page, controlled by the limit parameter. + example: 50 + current_page: + type: integer + description: | + The page you are currently on within the collection. + example: 1 + total_pages: + type: integer + description: | + The total number of pages in the collection. + example: 1 + links: + type: object + properties: + previous: + type: string + description: | + Link to the previous page returned in the response. + current: + type: string + description: | + Link to the current page returned in the response. + example: '?page=1&limit=50' + next: + type: string + description: | + Link to the next page returned in the response. + description: | + Pagination links for the previous and next parts of the whole collection. + description: 'Data about the response, including pagination and collection totals.' + x-internal: false + metaEmpty_Full: + type: object + title: Response meta + properties: {} + additionalProperties: true + description: Response metadata. + errorMultiStatus: + title: errorMultiStatus + type: object + properties: + status: + type: integer + minLength: 3 + maxLength: 3 + description: 'The [HTTP status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) of the failure or partial success.' + title: + type: string + description: A summary of the failure or partial success. + type: + type: string + description: A BigCommerce-defined error signifier. + errors: + $ref: '#/components/schemas/DetailedErrors' + DetailedErrors: + title: DetailedErrors + description: Each key-value pair describes a failure or partial success case. + type: object + properties: {} + additionalProperties: true + x-internal: false + metafield_Full: + title: metafield_Full + allOf: + - type: object + properties: + id: + type: integer + description: Unique ID of the *Metafield*. Read-Only. + readOnly: true + example: 6 + - $ref: '#/components/schemas/metafield_Base' + - type: object + properties: + resource_type: + type: string + description: | + The type of resource with which the metafield is associated. + example: product + enum: + - category + - brand + - product + - variant + x-required: + - post + resource_id: + maximum: 10000000000 + minimum: 0 + type: integer + description: | + The ID of the resource with which the metafield is associated. + example: 111 + x-required: + - post + date_created: + type: string + description: | + Date and time of the metafield's creation. Read-Only. + readOnly: true + format: date-time + example: '2018-05-07T20:14:17+00:00' + date_modified: + type: string + description: | + Date and time when the metafield was last updated. Read-Only. + readOnly: true + format: date-time + example: '2018-05-07T20:14:17+00:00' + x-internal: false + productVariant_Put: + title: productVariant_Put + description: The model for a PUT to update variants on a product. + allOf: + - $ref: '#/components/schemas/productVariant_Base' + - type: object + properties: + product_id: + type: integer + x-required: + - post + sku: + maxLength: 255 + minLength: 1 + type: string + x-required: + - post + x-internal: false + parameters: + ProductIdParam: + name: product_id + in: path + description: | + The ID of the `Product` to which the resource belongs. Product variant metafield endpoints that have the `product_id` in the request path are successful as long as the parameter is not empty. The `product_id` segment is there only for path consistency. + required: true + schema: + type: integer + VariantIdParam: + name: variant_id + in: path + description: | + ID of the variant on a product, or on an associated Price List Record. + required: true + schema: + type: integer + MetafieldIdParam: + name: metafield_id + in: path + description: | + The ID of the `Metafield`. + required: true + schema: + type: integer + Accept: + name: Accept + in: header + required: true + description: 'The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body.' + schema: + type: string + default: 'application/json' + ContentType: + name: Content-Type + in: header + required: true + description: 'The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the request body.' + schema: + type: string + default: 'application/json' + securitySchemes: + X-Auth-Token: + name: X-Auth-Token + description: |- + ### OAuth scopes + + | UI Name | Permission | Parameter | + |:--------|:-----------|:----------| + | Products | modify | `store_v2_products` | + | Products | read-only | `store_v2_products_read_only` | + + ### Authentication header + + | Header | Argument | Description | + |:-------|:---------|:------------| + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | + + ### Further reading + + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). + + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). + + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). + type: apiKey + in: header diff --git a/reference/catalog/products_catalog.v3.yml b/reference/catalog/products_catalog.v3.yml new file mode 100644 index 000000000..d40fd8f66 --- /dev/null +++ b/reference/catalog/products_catalog.v3.yml @@ -0,0 +1,8740 @@ +openapi: '3.0.3' +info: + title: Catalog - Products + description: |- + > The Catalog API manages products, categories, brands, bulk pricing rules, and more. To learn more about catalog resources, see the [Catalog Overview](/docs/store-operations/catalog). + + Our Catalog Products endpoints let you [create products](/docs/rest-catalog/products#create-a-product), perform [batch operations on existing products](/docs/rest-catalog/products#update-products-batch) and work with [reviews](/docs/rest-catalog/products/reviews), [images](/docs/rest-catalog/products/images), and [videos](/docs/rest-catalog/products/videos). Note that after a product is created initially, you can manage the nuances of its variations using the [Product Modifier](/docs/rest-catalog/product-modifiers), [Product Variant](/docs/rest-catalog/product-variants), and [Product Variant Options](/docs/rest-catalog/product-variant-options) endpoints. + + Other core product endpoints focus on [bulk pricing](/docs/rest-catalog/products/bulk-pricing-rules), [complex rules](/docs/rest-catalog/products/complex-rules), [custom fields](/docs/rest-catalog/products/custom-fields), and [metafields](/docs/rest-catalog/products/metafields). Product Variant objects also contain [their own metafields](/docs/rest-catalog/product-variants/metafields). For [MSF-enabled](/docs/storefront/multi-storefront) stores, the product object also contains product [channel assignments](/docs/rest-catalog/products/channel-assignments) and [category assignments](/docs/rest-catalog/products/category-assignments); read more about [products in the MSF context](/docs/storefront/multi-storefront/guide#products). + + This API family also contains an endpoint to [Get a catalog summary](/docs/rest-catalog/products/summary). + + > To learn more about authenticating Catalog endpoints, locate the **Authentication** section at the top of each endpoint, then click **Show Details**. + + ## Resources + + ### Webhooks + * [Product webhook events](/docs/integrations/webhooks/events#products) + * [Product assignment webhook events](/docs/integrations/webhooks/events/channels#product-assignments) + + ### Additional Catalog endpoints + * [Brands](/docs/rest-catalog/brands) + * [Categories](/docs/rest-catalog/categories) + * [Category Trees](/docs/rest-catalog/category-trees) + * [Product Modifiers](/docs/rest-catalog/product-modifiers) + * [Product Variants](/docs/rest-catalog/product-variants) + * [Product Variant Options](/docs/rest-catalog/product-variant-options) + + termsOfService: 'https://www.bigcommerce.com/terms' + contact: + name: BigCommerce + url: 'https://www.bigcommerce.com' + email: support@bigcommerce.com + version: '' +servers: + - url: 'https://api.bigcommerce.com/stores/{store_hash}/v3' + variables: + store_hash: + default: store_hash + description: Permanent ID of the BigCommerce store. + description: BigCommerce API Gateway +security: + - X-Auth-Token: [] +tags: + - name: Products + - name: Bulk Pricing Rules + - name: Complex Rules + - name: Custom Fields + - name: Images + - name: Metafields + - name: Reviews + - name: Videos + - name: Channel Assignments + - name: Category Assignments + - name: Summary +paths: + '/catalog/products': + get: + tags: + - Products + summary: Get All Products + description: Returns a list of **Products**. Optional filter parameters can be passed in. + operationId: getProducts + parameters: + - name: id + in: query + description: | + Filter items by ID. + schema: + type: integer + - name: 'id:in' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: 'id:not_in' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: 'id:min' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: 'id:max' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: 'id:greater' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: 'id:less' + in: query + style: form + explode: false + schema: + type: array + items: + type: integer + - name: name + in: query + description: | + Filter items by name. + schema: + type: string + - name: upc + in: query + description: | + Filter items by UPC. + schema: + type: string + - name: price + in: query + description: | + Filter items by price. + schema: + type: number + - name: weight + in: query + description: | + Filter items by weight. + schema: + type: number + - name: condition + in: query + description: | + Filter items by condition. + schema: + type: string + enum: + - new + - used + - refurbished + - name: brand_id + in: query + description: | + Filter items by brand_id. + schema: + type: integer + - name: date_modified + in: query + description: 'Filter items by `date_modified`. ' + schema: + type: string + format: date-time + - name: 'date_modified:max' + in: query + description: 'Filter items by `date_modified`. For example, `date_modified:max=2020-06-15`.' + schema: + type: string + - name: 'date_modified:min' + in: query + description: 'Filter items by `date_modified`. For example, `date_modified:min=2018-06-15`.' + schema: + type: string + - name: date_last_imported + in: query + description: Filter items by date_last_imported. + schema: + type: string + format: date-time + - name: 'date_last_imported:max' + in: query + description: 'Filter items by date_last_imported. For example, `date_last_imported:max=2020-06-15`.' + schema: + type: string + - name: 'date_last_imported:min' + in: query + description: 'Filter items by date_last_imported. For example, `date_last_imported:min=2018-06-15`.' + schema: + type: string + - name: is_visible + in: query + description: Filter items based on whether the product is currently visible on the storefront. + schema: + type: boolean + - name: is_featured + in: query + description: 'Filter items by is_featured. `1` for true, `0` for false.' + schema: + type: integer + enum: + - 1 + - 0 + - name: is_free_shipping + in: query + description: 'Filter items by is_free_shipping. `1` for true, `0` for false.' + schema: + type: integer + - name: inventory_level + in: query + description: | + Filter items by inventory_level. + schema: + type: integer + - name: 'inventory_level:in' + in: query + schema: + type: integer + - name: 'inventory_level:not_in' + in: query + schema: + type: integer + - name: 'inventory_level:min' + in: query + schema: + type: integer + - name: 'inventory_level:max' + in: query + schema: + type: integer + - name: 'inventory_level:greater' + in: query + schema: + type: integer + - name: 'inventory_level:less' + in: query + schema: + type: integer + - name: inventory_low + in: query + description: | + Filter items by inventory_low. Values: 1, 0. + schema: + type: integer + - name: out_of_stock + in: query + description: | + Filter items by out_of_stock. To enable the filter, pass `out_of_stock`=`1`. + schema: + type: integer + - name: total_sold + in: query + description: | + Filter items by total_sold. + schema: + type: integer + - name: type + in: query + description: Filter items by type. + schema: + type: string + enum: + - digital + - physical + - name: categories + in: query + description: |- + Filter items by categories. + If a product is in more than one category, using this query will not return the product. Instead use `categories:in=12`. + schema: + type: integer + - name: keyword + in: query + description: Filter items by keywords found in the `name` or `sku` fields + schema: + type: string + - name: keyword_context + in: query + description: Set context used by the search algorithm to return results targeted towards the specified group. Use `merchant` to help merchants search their own catalog. Use `shopper` to return shopper-facing search results. + schema: + type: string + enum: + - shopper + - merchant + - name: status + in: query + description: | + Filter items by status. + schema: + type: integer + - name: include + in: query + description: |- + Sub-resources to include on a product, in a comma-separated list. If `options` or `modifiers` is used, results are limited to 10 per page. + + **Note:** The following sub-resources include: + * variants + * images + * custom_fields + * bulk_pricing_rules + * primary_images + * modifiers + * options + * videos + explode: false + schema: + type: array + items: + type: string + enum: + - variants + - images + - custom_fields + - bulk_pricing_rules + - primary_image + - modifiers + - options + - videos + - name: include_fields + in: query + description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' + schema: + type: string + - name: exclude_fields + in: query + description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' + schema: + type: string + - name: availability + in: query + description: | + Filter items by availability. Values are: available, disabled, preorder. + schema: + type: string + enum: + - available + - disabled + - preorder + - name: page + in: query + description: Specifies the page number in a limited (paginated) list of products. + schema: + type: integer + - name: limit + in: query + description: Controls the number of items per page in a limited (paginated) list of products. The default product limit is 50 with a maximum limit of 250. + schema: + type: integer + - name: direction + in: query + description: | + Sort direction. Acceptable values are: `asc`, `desc`. + schema: + type: string + enum: + - asc + - desc + - name: sort + in: query + description: | + Field name to sort by. Note: Since `id` increments when new products are added, you can use that field to sort by product create date. + schema: + type: string + enum: + - id + - name + - sku + - price + - date_modified + - date_last_imported + - inventory_level + - is_visible + - total_sold + - name: 'categories:in' + in: query + description: 'Filter items by categories. Use for products in multiple categories. For example, `categories:in=12`.' + schema: + type: integer + - name: sku + in: query + description: 'Filter items by main SKU. To filter by variant SKU, see [Get All Variants](/docs/rest-catalog/product-variants#get-all-product-variants). ' + schema: + type: string + - name: 'sku:in' + in: query + description: Filter items by SKU. + style: form + explode: false + schema: + type: array + items: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/product_Full' + meta: + $ref: '#/components/schemas/metaCollection_Full' + put: + tags: + - Products + summary: Update Products (Batch) + description: |- + Updates products in batches. Batches are limited to 10 products. + + **Required Fields** + * `id` - product `id` is required for batch updates to products. + + **Read-Only Fields** + - `id` + - `date_created` + - `date_modified` + - `calculated_price` + - `base_variant_id` + operationId: updateProducts + parameters: + - $ref: '#/components/parameters/ContentType' + - name: include_fields + in: query + description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/product_Put_Collection' + examples: + example-1: + value: + - id: 0 + name: Smith Journal 13 + type: physical + sku: SM-13 + description: '<p><span>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vel metus ac est egestas porta sed quis erat. Integer id nulla massa. Proin vitae enim nisi. Praesent non dignissim nulla. Nulla mattis id massa ac pharetra. Mauris et nisi in dolor aliquam sodales. Aliquam dui nisl, dictum quis leo sit amet, rutrum volutpat metus. Curabitur libero nunc, interdum ac libero non, tristique porttitor metus. Ut non dignissim lorem, in vestibulum leo. Vivamus sodales quis turpis eget.</span></p>' + weight: 0 + width: 0 + depth: 0 + height: 0 + price: 0 + cost_price: 0 + retail_price: 0 + sale_price: 0 + map_price: 0 + tax_class_id: 0 + product_tax_code: string + categories: + - 0 + brand_id: 0 + inventory_level: 0 + inventory_warning_level: 0 + inventory_tracking: none + fixed_cost_shipping_price: 0 + is_free_shipping: true + is_visible: true + is_featured: true + related_products: + - 0 + warranty: string + bin_picking_number: string + layout_file: string + upc: string + search_keywords: string + availability: available + availability_description: string + gift_wrapping_options_type: any + gift_wrapping_options_list: + - 0 + sort_order: -2147483648 + condition: New + is_condition_shown: true + order_quantity_minimum: 0 + order_quantity_maximum: 0 + page_title: string + meta_keywords: + - string + meta_description: string + view_count: 0 + preorder_release_date: '2019-08-24T14:15:22Z' + preorder_message: string + is_preorder_only: true + is_price_hidden: true + price_hidden_label: string + custom_url: + url: string + is_customized: true + open_graph_type: product + open_graph_title: string + open_graph_description: string + open_graph_use_meta_description: true + open_graph_use_product_name: true + open_graph_use_image: true + brand_name: Common Good + gtin: string + mpn: string + reviews_rating_sum: 3 + reviews_count: 4 + total_sold: 80 + custom_fields: + - id: 6 + name: ISBN + value: '1234567890123' + bulk_pricing_rules: + - id: 0 + quantity_min: 10 + quantity_max: 50 + type: price + amount: 10 + images: + - image_file: string + is_thumbnail: true + sort_order: -2147483648 + description: string + image_url: string + id: 0 + product_id: 0 + url_zoom: string + url_standard: string + url_thumbnail: string + url_tiny: string + date_modified: '2019-08-24T14:15:22Z' + videos: + - title: Writing Great Documentation + description: A video about documentation. + sort_order: 1 + type: youtube + video_id: z3fRu9pkuXE + id: 0 + product_id: 0 + length: string + required: false + responses: + '200': + description: '' + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/product_Full' + meta: + $ref: '#/components/schemas/metaCollection_Full' + examples: + example-1: + value: + data: + - id: 1 + name: Smith Journal 13 + type: physical + sku: SM-13 + description: '<p><span>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vel metus ac est egestas porta sed quis erat. Integer id nulla massa. Proin vitae enim nisi. Praesent non dignissim nulla. Nulla mattis id massa ac pharetra. Mauris et nisi in dolor aliquam sodales. Aliquam dui nisl, dictum quis leo sit amet, rutrum volutpat metus. Curabitur libero nunc, interdum ac libero non, tristique porttitor metus. Ut non dignissim lorem, in vestibulum leo. Vivamus sodales quis turpis eget.</span></p>' + weight: 0 + width: 0 + depth: 0 + height: 0 + price: 0 + cost_price: 0 + retail_price: 0 + sale_price: 0 + map_price: 0 + tax_class_id: 0 + product_tax_code: string + categories: + - 0 + brand_id: 0 + inventory_level: 0 + inventory_warning_level: 0 + inventory_tracking: none + fixed_cost_shipping_price: 0 + is_free_shipping: true + is_visible: true + is_featured: true + related_products: + - 0 + warranty: string + bin_picking_number: string + layout_file: string + upc: string + search_keywords: string + availability: available + availability_description: string + gift_wrapping_options_type: any + gift_wrapping_options_list: + - 0 + sort_order: -2147483648 + condition: New + is_condition_shown: true + order_quantity_minimum: 0 + order_quantity_maximum: 0 + page_title: string + meta_keywords: + - string + meta_description: string + view_count: 0 + preorder_release_date: '2019-08-24T14:15:22Z' + preorder_message: string + is_preorder_only: true + is_price_hidden: true + price_hidden_label: string + custom_url: + url: string + is_customized: true + open_graph_type: product + open_graph_title: string + open_graph_description: string + open_graph_use_meta_description: true + open_graph_use_product_name: true + open_graph_use_image: true + brand_name: Common Good + gtin: string + mpn: string + reviews_rating_sum: 3 + reviews_count: 4 + total_sold: 80 + custom_fields: + - id: 6 + name: ISBN + value: '1234567890123' + bulk_pricing_rules: + - id: 0 + quantity_min: 10 + quantity_max: 50 + type: price + amount: 10 + images: + - image_file: string + is_thumbnail: true + sort_order: -2147483648 + description: string + image_url: string + id: 0 + product_id: 0 + url_zoom: string + url_standard: string + url_thumbnail: string + url_tiny: string + date_modified: '2019-08-24T14:15:22Z' + videos: + - title: Writing Great Documentation + description: A video about documentation + sort_order: 1 + type: youtube + video_id: z3fRu9pkuXE + id: 0 + product_id: 0 + length: string + date_created: '2018-08-15T14:49:05+00:00' + date_modified: '2018-08-24T14:41:00+00:00' + base_variant_id: 0 + calculated_price: 0 + options: + - id: 55 + product_id: 4 + display_name: Add-a-$5-Donation1535042499-187 + type: radio_buttons + config: + default_value: string + checked_by_default: true + checkbox_label: string + date_limited: true + date_limit_mode: range + date_earliest_value: '2019-08-24' + date_latest_value: '2019-08-24' + file_types_mode: specific + file_types_supported: + - 'images, documents, other' + file_types_other: + - pdf + file_max_size: 5 + text_characters_limited: true + text_min_length: 1 + text_max_length: 55 + text_lines_limited: true + text_max_lines: 4 + number_limited: true + number_limit_mode: lowest + number_lowest_value: 100 + number_highest_value: 0 + number_integers_only: false + product_list_adjusts_inventory: true + product_list_adjusts_pricing: true + product_list_shipping_calc: weight + sort_order: 1 + option_values: + - is_default: false + label: Green + sort_order: 0 + value_data: {} + id: 0 + modifiers: + - type: date + required: true + sort_order: 0 + config: + default_value: string + checked_by_default: true + checkbox_label: string + date_limited: true + date_limit_mode: range + date_earliest_value: '2019-08-24' + date_latest_value: '2019-08-24' + file_types_mode: specific + file_types_supported: + - 'images, documents, other' + file_types_other: + - pdf + file_max_size: 5 + text_characters_limited: true + text_min_length: 1 + text_max_length: 55 + text_lines_limited: true + text_max_lines: 4 + number_limited: true + number_limit_mode: lowest + number_lowest_value: 100 + number_highest_value: 0 + number_integers_only: false + product_list_adjusts_inventory: true + product_list_adjusts_pricing: true + product_list_shipping_calc: weight + display_name: string + id: 12 + product_id: 77 + name: Add-a-$5-Donation1535039590-191 + option_values: + - is_default: false + label: Green + sort_order: 0 + value_data: {} + adjusters: + price: + adjuster: relative + adjuster_value: 5 + weight: + adjuster: relative + adjuster_value: 5 + image_url: 'https://cdn8.bigcommerce.com/s-{{store_hash}}/products/184/images/445/naturalcanvascart2_1024x1024__92347__29648.1534344533.1280.1280.jpg?c=2' + purchasing_disabled: + status: true + message: string + id: 0 + option_id: 0 + option_set_id: 0 + option_set_display: string + variants: + - cost_price: 0 + price: 0 + sale_price: 0 + retail_price: 0 + weight: 0 + width: 0 + height: 0 + depth: 0 + is_free_shipping: true + fixed_cost_shipping_price: 0 + purchasing_disabled: true + purchasing_disabled_message: string + upc: string + inventory_level: 0 + inventory_warning_level: 0 + bin_picking_number: string + mpn: string + gtin: '012345678905' + id: 0 + product_id: 0 + sku: string + sku_id: 0 + option_values: + - option_display_name: Color + label: Beige + id: 146 + option_id: 151 + calculated_price: 0 + calculated_weight: 0 + meta: + pagination: + total: 36 + count: 36 + per_page: 50 + current_page: 1 + total_pages: 1 + links: + previous: string + current: '?page=1&limit=50' + next: string + '207': + description: |- + Multi-status. The product information was updated successfully, but the inventory data failed to update. + + Verify that the inventory-related updates are well-formed and correct; for example, that they donʼt result in negative stock levels. Then consider updating the inventory data again. + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/product_Full' + errors: + $ref: '#/components/schemas/errorMultiStatus' + meta: + $ref: '#/components/schemas/metaCollection_Full' + '404': + description: The resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + '409': + description: '`Product` was in conflict with another product. This is the result of duplicate unique values such as name or SKU; a missing or invalid `category_id`, `brand_id`, or `tax_class id`; or a conflicting `bulk_pricing_rule`.' + content: + application/json: + schema: + $ref: '#/components/schemas/errorResponse_409' + '413': + description: 413 Request Entity Too Large + content: + application/json: + schema: + $ref: '#/components/schemas/error_Base' + example: + errors: {} + status: 413 + title: The request payload is too large. The maximum items allowed in the array is 10. + type: /api-docs/getting-started/api-status-codes + '422': + description: '`Product` was not valid. This is the result of missing required fields or invalid data. See the response for more details.' + content: + application/json: + schema: + $ref: '#/components/schemas/errorResponse_422' + x-codegen-request-body-name: products + post: + tags: + - Products + summary: Create a Product + description: |- + Creates a *Product*. Only one product can be created at a time. + + **Required Fields:** + - `name` + - `type` + - `weight` + - `price` + + **Read-Only Fields** + - `id` + - `date_created` + - `date_modified` + - `calculated_price` + - `base_variant_id` + + **Limits** + - 250 characters product name length. + - A product can have up to 1000 images. Each image file or image uploaded by URL can be up to 8 MB. + + **Usage Notes** + * This endpoint accepts a `video` array. To create a product video that accepts a `video` object, see [Create a Product Video](/docs/rest-catalog/products/videos#create-a-product-video) for information. + + operationId: createProduct + parameters: + - $ref: '#/components/parameters/ContentType' + - name: include_fields + in: query + description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/product_Base' + required: true + responses: + '200': + description: '' + content: + application/json: + schema: + title: Product Response + type: object + properties: + data: + $ref: '#/components/schemas/product_Full' + meta: + $ref: '#/components/schemas/metaEmpty_Full' + example-1: + example: + name: Smith Journal 13 + type: physical + sku: SM-13 + description: '<p><span>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vel metus ac est egestas porta sed quis erat. Integer id nulla massa. Proin vitae enim nisi. Praesent non dignissim nulla. Nulla mattis id massa ac pharetra. Mauris et nisi in dolor aliquam sodales. Aliquam dui nisl, dictum quis leo sit amet, rutrum volutpat metus. Curabitur libero nunc, interdum ac libero non, tristique porttitor metus. Ut non dignissim lorem, in vestibulum leo. Vivamus sodales quis turpis eget.</span></p>' + weight: 0 + width: 0 + depth: 0 + height: 0 + price: 0 + cost_price: 0 + retail_price: 0 + sale_price: 0 + map_price: 0 + tax_class_id: 0 + product_tax_code: string + categories: + - 0 + brand_id: 0 + inventory_level: 0 + inventory_warning_level: 0 + inventory_tracking: none + fixed_cost_shipping_price: 0 + is_free_shipping: true + is_visible: true + is_featured: true + related_products: + - 0 + warranty: string + bin_picking_number: string + layout_file: string + upc: string + search_keywords: string + availability: available + availability_description: string + gift_wrapping_options_type: any + gift_wrapping_options_list: + - 0 + sort_order: -2147483648 + condition: New + is_condition_shown: true + order_quantity_minimum: 0 + order_quantity_maximum: 0 + page_title: string + meta_keywords: + - string + meta_description: string + view_count: 0 + preorder_release_date: '2019-08-24T14:15:22+00:00' + preorder_message: string + is_preorder_only: true + is_price_hidden: true + price_hidden_label: string + custom_url: + url: string + is_customized: true + open_graph_type: product + open_graph_title: string + open_graph_description: string + open_graph_use_meta_description: true + open_graph_use_product_name: true + open_graph_use_image: true + brand_name: Common Good + gtin: string + mpn: string + reviews_rating_sum: 3.2 + reviews_count: 4 + total_sold: 80 + custom_fields: + - id: 6 + name: ISBN + value: '1234567890123' + bulk_pricing_rules: + - id: 0 + quantity_min: 10 + quantity_max: 50 + type: price + amount: 10 + images: + - image_file: string + is_thumbnail: true + sort_order: -2147483648 + description: string + image_url: string + id: 0 + product_id: 0 + url_zoom: string + url_standard: string + url_thumbnail: string + url_tiny: string + date_modified: '2019-08-24T14:15:22+00:00' + videos: + - title: string + description: string + sort_order: -2147483648 + type: youtube + video_id: string + id: 0 + product_id: 0 + length: string + date_created: '2018-08-15T14:49:05+00:00' + date_modified: '2018-08-24T14:41:00+00:00' + id: 1 + base_variant_id: 0 + calculated_price: 0 + options: + - id: 55 + product_id: 4 + display_name: Add-a-$5-Donation1535042499-187 + type: radio_buttons + config: + default_value: string + checked_by_default: true + checkbox_label: string + date_limited: true + date_limit_mode: range + date_earliest_value: '2019-08-24T00:00:00+00:00' + date_latest_value: '2019-08-24T00:00:00+00:00' + file_types_mode: specific + file_types_supported: + - 'images, documents, other' + file_types_other: + - pdf + file_max_size: 5 + text_characters_limited: true + text_min_length: 1 + text_max_length: 55 + text_lines_limited: true + text_max_lines: 4 + number_limited: true + number_limit_mode: lowest + number_lowest_value: 100 + number_highest_value: 0 + number_integers_only: false + product_list_adjusts_inventory: true + product_list_adjusts_pricing: true + product_list_shipping_calc: weight + sort_order: 1 + option_values: + is_default: false + label: Green + sort_order: 0 + value_data: {} + id: 0 + modifiers: + - type: date + required: true + sort_order: 0 + config: + default_value: string + checked_by_default: true + checkbox_label: string + date_limited: true + date_limit_mode: range + date_earliest_value: '2019-08-24T00:00:00+00:00' + date_latest_value: '2019-08-24T00:00:00+00:00' + file_types_mode: specific + file_types_supported: + - 'images, documents, other' + file_types_other: + - pdf + file_max_size: 5 + text_characters_limited: true + text_min_length: 1 + text_max_length: 55 + text_lines_limited: true + text_max_lines: 4 + number_limited: true + number_limit_mode: lowest + number_lowest_value: 100 + number_highest_value: 0 + number_integers_only: false + product_list_adjusts_inventory: true + product_list_adjusts_pricing: true + product_list_shipping_calc: weight + display_name: string + id: 12 + product_id: 77 + name: Add-a-$5-Donation1535039590-191 + option_values: + - is_default: false + label: Green + sort_order: 0 + value_data: {} + adjusters: + price: + adjuster: relative + adjuster_value: 5 + weight: + adjuster: relative + adjuster_value: 5 + image_url: 'https://cdn8.bigcommerce.com/s-{{store_hash}}/products/184/images/445/naturalcanvascart2_1024x1024__92347__29648.1534344533.1280.1280.jpg?c=2' + purchasing_disabled: + status: true + message: string + id: 0 + option_id: 0 + option_set_id: 0 + option_set_display: string + variants: + - cost_price: 0 + price: 0 + sale_price: 0 + retail_price: 0 + weight: 0 + width: 0 + height: 0 + depth: 0 + is_free_shipping: true + fixed_cost_shipping_price: 0 + purchasing_disabled: true + purchasing_disabled_message: string + upc: string + inventory_level: 0 + inventory_warning_level: 0 + bin_picking_number: string + mpn: string + gtin: '012345678905' + id: 0 + product_id: 0 + sku: string + sku_id: 0 + option_values: + - option_display_name: Color + label: Beige + id: 146 + option_id: 151 + calculated_price: 0 + calculated_weight: 0 + meta: {} + '207': + '207': + description: |- + Multi-status. The product information was updated successfully, but the inventory data failed to update. + + Verify that the inventory-related updates are well-formed and correct; for example, that they donʼt result in negative stock levels. Then consider updating the inventory data again. + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/product_Full' + errors: + $ref: '#/components/schemas/errorMultiStatus' + meta: + $ref: '#/components/schemas/metaCollection_Full' + + '409': + description: | + `Product` was in conflict with another product. This is the result of duplicate unique values, such as name or SKU; a missing or invalid `category_id`, `brand_id`, or `tax_class id`; or a conflicting `bulk_pricing_rule`. + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + '422': + description: | + `Product` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + x-codegen-request-body-name: product + delete: + tags: + - Products + summary: Delete Products + description: |- + To delete *Product* objects, you must include a filter. This prevents inadvertently deleting all *Product* objects in a store. + + > #### Note + > The maximum number of products you can delete at one time is 250. + + **Example**: + To delete products with the id's of 1,2 and 3, use `DELETE /v3/catalog/products?id:in=1,2,3`. + operationId: deleteProducts + parameters: + - name: name + in: query + description: | + Filter items by name. + schema: + type: string + - name: sku + in: query + description: | + Filter items by SKU. + schema: + type: string + - name: price + in: query + description: | + Filter items by price. + schema: + type: number + - name: weight + in: query + description: | + Filter items by weight. + schema: + type: number + - name: condition + in: query + description: | + Filter items by condition. + schema: + type: string + enum: + - new + - used + - refurbished + - name: brand_id + in: query + description: | + Filter items by brand_id. + schema: + type: integer + - name: date_modified + in: query + description: 'Filter items by date_modified. For example `v3/catalog/products?date_modified:min=2018-06-15`' + schema: + type: string + format: date-time + - name: date_last_imported + in: query + description: 'Filter items by date_last_imported. For example `v3/catalog/products?date_last_imported:min=2018-06-15`' + schema: + type: string + format: date-time + - name: is_visible + in: query + description: 'Filter items by if visible on the storefront. ' + schema: + type: boolean + - name: is_featured + in: query + description: | + Filter items by is_featured. + schema: + type: integer + - name: 'id:in' + in: query + description: + Filter by product ID(s). + style: form + explode: false + schema: + type: array + items: + type: integer + - name: inventory_level + in: query + description: | + Filter items by inventory_level. + schema: + type: integer + - name: total_sold + in: query + description: | + Filter items by total_sold. + schema: + type: integer + - name: type + in: query + description: 'Filter items by type: `physical` or `digital`.' + schema: + type: string + enum: + - digital + - physical + - name: categories + in: query + description: |- + Filter items by categories. + If a product is in more than one category, using this query will not return the product. Instead use `categories:in=12`. + schema: + type: integer + - name: keyword + in: query + description: | + Filter items by keywords found in the `name`, `description`, or `sku` fields, or in the brand name. + schema: + type: string + responses: + '204': + description: '' + content: {} + parameters: + - $ref: '#/components/parameters/Accept' + '/catalog/products/{product_id}': + get: + tags: + - Products + summary: Get a Product + description: Returns a single *Product*. Optional parameters can be passed in. + operationId: getProductById + parameters: + - name: include + in: query + description: 'Sub-resources to include on a product, in a comma-separated list. If `options` or `modifiers` is used, results are limited to 10 per page.' + explode: false + schema: + type: array + items: + type: string + enum: + - variants + - images + - custom_fields + - bulk_pricing_rules + - primary_image + - modifiers + - options + - videos + - name: include_fields + in: query + description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' + schema: + type: string + - name: exclude_fields + in: query + description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + title: Product Response + type: object + properties: + data: + $ref: '#/components/schemas/product_Full' + meta: + $ref: '#/components/schemas/metaEmpty_Full' + example: + data: + id: 174 + name: 1L Le Parfait Jar + type: physical + sku: '' + description: '<p><span>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vel metus ac est egestas porta sed quis erat. Integer id nulla massa. Proin vitae enim nisi. Praesent non dignissim nulla. Nulla mattis id massa ac pharetra. Mauris et nisi in dolor aliquam sodales. Aliquam dui nisl, dictum quis leo sit amet, rutrum volutpat metus. Curabitur libero nunc, interdum ac libero non, tristique porttitor metus. Ut non dignissim lorem, in vestibulum leo. Vivamus sodales quis turpis eget.</span></p>' + weight: 1 + width: 0 + depth: 0 + height: 0 + price: 7.95 + cost_price: 0 + retail_price: 10 + sale_price: 0 + map_price: 0 + tax_class_id: 0 + product_tax_code: '' + calculated_price: 7.95 + categories: + - 23 + - 21 + brand_id: 36 + option_set_id: 55 + option_set_display: right + inventory_level: 0 + inventory_warning_level: 0 + inventory_tracking: none + reviews_rating_sum: 0 + reviews_count: 0 + total_sold: 7 + fixed_cost_shipping_price: 0 + is_free_shipping: false + is_visible: true + is_featured: false + related_products: + - -1 + warranty: '' + bin_picking_number: '' + layout_file: product.html + upc: '' + mpn: '' + gtin: '' + search_keywords: 'jar, glass' + availability: available + availability_description: '' + gift_wrapping_options_type: any + gift_wrapping_options_list: [] + sort_order: 0 + condition: New + is_condition_shown: false + order_quantity_minimum: 0 + order_quantity_maximum: 0 + page_title: '' + meta_keywords: [] + meta_description: '' + date_created: '2018-08-15T14:48:46+00:00' + date_modified: '2018-09-05T20:42:07+00:00' + view_count: 10 + preorder_release_date: '2018-09-05T20:42:07+00:00' + preorder_message: '' + is_preorder_only: false + is_price_hidden: false + price_hidden_label: '' + custom_url: + url: /all/1l-le-parfait-jar/ + is_customized: true + base_variant_id: 345 + open_graph_type: product + open_graph_title: '' + open_graph_description: '' + open_graph_use_meta_description: true + open_graph_use_product_name: true + open_graph_use_image: true + meta: {} + '404': + description: | + The resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + put: + tags: + - Products + summary: Update a Product + description: | + Updates a *Product*. + + **Limits** + - A product can have up to 1000 images. Each image file or image uploaded by URL can be up to 8 MB. + + **Read-Only Fields** + - id + - date_created + - date_modified + - calculated_price + - base_variant_id + operationId: updateProduct + parameters: + - $ref: '#/components/parameters/ContentType' + - name: include_fields + in: query + description: 'Sub-resources to include on a product, in a comma-separated list. If `options` or `modifiers` is used, results are limited to 10 per page. The ID and the specified fields will be returned.' + schema: + type: string + enum: + - variants + - images + - custom_fields + - bulk_pricing_rules + - primary_image + - modifiers + - options + - videos + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/product_Put' + required: true + responses: + '200': + description: '' + content: + application/json: + schema: + title: Product Response + type: object + properties: + data: + $ref: '#/components/schemas/product_Full' + meta: + $ref: '#/components/schemas/metaEmpty_Full' + example-1: + example: + name: Smith Journal 13 + type: physical + sku: SM-13 + description: '<p><span>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vel metus ac est egestas porta sed quis erat. Integer id nulla massa. Proin vitae enim nisi. Praesent non dignissim nulla. Nulla mattis id massa ac pharetra. Mauris et nisi in dolor aliquam sodales. Aliquam dui nisl, dictum quis leo sit amet, rutrum volutpat metus. Curabitur libero nunc, interdum ac libero non, tristique porttitor metus. Ut non dignissim lorem, in vestibulum leo. Vivamus sodales quis turpis eget.</span></p>' + weight: 0 + width: 0 + depth: 0 + height: 0 + price: 0 + cost_price: 0 + retail_price: 0 + sale_price: 0 + map_price: 0 + tax_class_id: 0 + product_tax_code: string + categories: + - 0 + brand_id: 0 + inventory_level: 0 + inventory_warning_level: 0 + inventory_tracking: none + fixed_cost_shipping_price: 0 + is_free_shipping: true + is_visible: true + is_featured: true + related_products: + - 0 + warranty: string + bin_picking_number: string + layout_file: string + upc: string + search_keywords: string + availability: available + availability_description: string + gift_wrapping_options_type: any + gift_wrapping_options_list: + - 0 + sort_order: -2147483648 + condition: New + is_condition_shown: true + order_quantity_minimum: 0 + order_quantity_maximum: 0 + page_title: string + meta_keywords: + - string + meta_description: string + view_count: 0 + preorder_release_date: '2019-08-24T14:15:22+00:00' + preorder_message: string + is_preorder_only: true + is_price_hidden: true + price_hidden_label: string + custom_url: + url: string + is_customized: true + open_graph_type: product + open_graph_title: string + open_graph_description: string + open_graph_use_meta_description: true + open_graph_use_product_name: true + open_graph_use_image: true + brand_name: Common Good + gtin: string + mpn: string + reviews_rating_sum: 3.2 + reviews_count: 4 + total_sold: 80 + custom_fields: + - id: 6 + name: ISBN + value: '1234567890123' + bulk_pricing_rules: + - id: 0 + quantity_min: 10 + quantity_max: 50 + type: price + amount: 10 + images: + - image_file: string + is_thumbnail: true + sort_order: -2147483648 + description: string + image_url: string + id: 0 + product_id: 0 + url_zoom: string + url_standard: string + url_thumbnail: string + url_tiny: string + date_modified: '2019-08-24T14:15:22+00:00' + videos: + - title: string + description: string + sort_order: -2147483648 + type: youtube + video_id: string + id: 0 + product_id: 0 + length: string + date_created: '2018-08-15T14:49:05+00:00' + date_modified: '2018-08-24T14:41:00+00:00' + id: 1 + base_variant_id: 0 + calculated_price: 0 + options: + - id: 55 + product_id: 4 + display_name: Add-a-$5-Donation1535042499-187 + type: radio_buttons + config: + default_value: string + checked_by_default: true + checkbox_label: string + date_limited: true + date_limit_mode: range + date_earliest_value: '2019-08-24T00:00:00+00:00' + date_latest_value: '2019-08-24T00:00:00+00:00' + file_types_mode: specific + file_types_supported: + - 'images, documents, other' + file_types_other: + - pdf + file_max_size: 5 + text_characters_limited: true + text_min_length: 1 + text_max_length: 55 + text_lines_limited: true + text_max_lines: 4 + number_limited: true + number_limit_mode: lowest + number_lowest_value: 100 + number_highest_value: 0 + number_integers_only: false + product_list_adjusts_inventory: true + product_list_adjusts_pricing: true + product_list_shipping_calc: weight + sort_order: 1 + option_values: + is_default: false + label: Green + sort_order: 0 + value_data: {} + id: 0 + modifiers: + - type: date + required: true + sort_order: 0 + config: + default_value: string + checked_by_default: true + checkbox_label: string + date_limited: true + date_limit_mode: range + date_earliest_value: '2019-08-24T00:00:00+00:00' + date_latest_value: '2019-08-24T00:00:00+00:00' + file_types_mode: specific + file_types_supported: + - 'images, documents, other' + file_types_other: + - pdf + file_max_size: 5 + text_characters_limited: true + text_min_length: 1 + text_max_length: 55 + text_lines_limited: true + text_max_lines: 4 + number_limited: true + number_limit_mode: lowest + number_lowest_value: 100 + number_highest_value: 0 + number_integers_only: false + product_list_adjusts_inventory: true + product_list_adjusts_pricing: true + product_list_shipping_calc: weight + display_name: string + id: 12 + product_id: 77 + name: Add-a-$5-Donation1535039590-191 + option_values: + - is_default: false + label: Green + sort_order: 0 + value_data: {} + adjusters: + price: + adjuster: relative + adjuster_value: 5 + weight: + adjuster: relative + adjuster_value: 5 + image_url: 'https://cdn8.bigcommerce.com/s-{{store_hash}}/products/184/images/445/naturalcanvascart2_1024x1024__92347__29648.1534344533.1280.1280.jpg?c=2' + purchasing_disabled: + status: true + message: string + id: 0 + option_id: 0 + option_set_id: 0 + option_set_display: string + variants: + - cost_price: 0 + price: 0 + sale_price: 0 + retail_price: 0 + weight: 0 + width: 0 + height: 0 + depth: 0 + is_free_shipping: true + fixed_cost_shipping_price: 0 + purchasing_disabled: true + purchasing_disabled_message: string + upc: string + inventory_level: 0 + inventory_warning_level: 0 + bin_picking_number: string + mpn: string + gtin: 12345678905 + id: 0 + product_id: 0 + sku: string + sku_id: 0 + option_values: + - option_display_name: Color + label: Beige + id: 146 + option_id: 151 + calculated_price: 0 + calculated_weight: 0 + meta: {} + '201': + description: Created + content: + application/json: + schema: + type: object + properties: {} + '207': + description: |- + Multi-status. The product information was updated successfully, but the inventory data failed to update. + + Verify that the inventory-related updates are well-formed and correct; for example, that they donʼt result in negative stock levels. Then consider updating the inventory data again. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/product_Full' + errors: + $ref: '#/components/schemas/errorMultiStatus' + meta: + $ref: '#/components/schemas/metaCollection_Full' + '404': + description: | + The resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + '409': + description: | + `Product` was in conflict with another product. This is caused by: duplicate unique values, such as name or SKU; a missing category, brand, or tax_class with which the product is being associated; or a conflicting bulk pricing rule. + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + '422': + description: | + `Product` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + x-codegen-request-body-name: product + delete: + tags: + - Products + summary: Delete a Product + description: Deletes a *Product*. + operationId: deleteProductById + responses: + '204': + description: '' + content: {} + parameters: + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/ProductIdParam' + '/catalog/products/{product_id}/images': + get: + tags: + - Images + summary: Get All Product Images + description: Returns a list of *Product Images*. Optional parameters can be passed in. + operationId: getProductImages + parameters: + - name: page + in: query + description: Specifies the page number in a limited (paginated) list of products. + schema: + type: integer + - name: limit + in: query + description: Controls the number of items per page in a limited (paginated) list of products. + schema: + type: integer + - name: include_fields + in: query + description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' + schema: + type: string + - name: exclude_fields + in: query + description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + title: Product Image Collection Response + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/productImage_Full' + meta: + $ref: '#/components/schemas/metaCollection_Full' + description: | + Response payload for the BigCommerce API. + example: + data: + - id: 382 + product_id: 158 + is_thumbnail: true + sort_order: 0 + description: '' + image_file: a/521/foglinenbeigestripetowel1b_1024x1024__83011__60806.jpg + url_zoom: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/382/foglinenbeigestripetowel1b_1024x1024__83011__60806.1534344511.1280.1280.jpg?c=2' + url_standard: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/382/foglinenbeigestripetowel1b_1024x1024__83011__60806.1534344511.560.850.jpg?c=2' + url_thumbnail: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/382/foglinenbeigestripetowel1b_1024x1024__83011__60806.1534344511.330.500.jpg?c=2' + url_tiny: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/382/foglinenbeigestripetowel1b_1024x1024__83011__60806.1534344511.66.100.jpg?c=2' + date_modified: '2018-08-15T14:48:31+00:00' + - id: 383 + product_id: 158 + is_thumbnail: false + sort_order: 0 + description: '' + image_file: k/050/foglinenbeigestripetowel2b_1024x1024__16082__46564.jpg + url_zoom: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/383/foglinenbeigestripetowel2b_1024x1024__16082__46564.1534344511.1280.1280.jpg?c=2' + url_standard: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/383/foglinenbeigestripetowel2b_1024x1024__16082__46564.1534344511.560.850.jpg?c=2' + url_thumbnail: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/383/foglinenbeigestripetowel2b_1024x1024__16082__46564.1534344511.330.500.jpg?c=2' + url_tiny: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/383/foglinenbeigestripetowel2b_1024x1024__16082__46564.1534344511.66.100.jpg?c=2' + date_modified: '2018-08-15T14:48:31+00:00' + meta: + pagination: + total: 2 + count: 2 + per_page: 50 + current_page: 1 + total_pages: 1 + links: + current: '?page=1&limit=50' + '204': + description: | + There are not any images on this product. + content: {} + '404': + description: | + The product ID does not exist. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + post: + tags: + - Images + summary: Create a Product Image + description: |- + Creates a *Product Image*. + + **Required Fields** + - `image_file`, or + - `image_url` + + **Usage Notes** + - `image_url` - `255` character limit + - For file uploads, use the `multipart/form-data` media type. + - You can create only one image at a time. A product can have up to 1000 images. + - Supported image file types are BMP, GIF, JPEG, PNG, WBMP, XBM, and WEBP. + - Each image file or image uploaded by URL can be up to 8 MB. + operationId: createProductImage + parameters: + - $ref: '#/components/parameters/ContentType' + requestBody: + content: + application/json: + schema: + title: Product Image Post + description: The model for a POST to create an image on a product. + allOf: + - title: Product Image Base + type: object + properties: + product_id: + type: integer + description: | + The unique numeric identifier for the product with which the image is associated. + url_zoom: + readOnly: true + type: string + description: | + The zoom URL for this image. By default, this is used as the zoom image on product pages when zoom images are enabled. + url_standard: + readOnly: true + type: string + description: | + The standard URL for this image. By default, this is used for product-page images. + url_thumbnail: + readOnly: true + type: string + description: | + The thumbnail URL for this image. By default, this is the image size used on the category page and in side panels. + url_tiny: + readOnly: true + type: string + description: | + The tiny URL for this image. By default, this is the image size used for thumbnails beneath the product image on a product page. + date_modified: + type: string + description: | + The date on which the product image was modified. + format: date-time + is_thumbnail: + type: boolean + description: | + Flag for identifying whether the image is used as the product's thumbnail. + sort_order: + maximum: 2147483647 + minimum: -2147483648 + type: integer + description: | + The order in which the image will be displayed on the product page. Higher integers give the image a lower priority. When updating, if the image is given a lower priority, all images with a `sort_order` the same as or greater than the image's new `sort_order` value will have their `sort_order`s reordered. + description: + type: string + description: | + The description for the image. + description: Common ProductImage properties. + - type: object + properties: + image_url: + type: string + description: | + Must be a fully qualified URL path, including protocol. Limit of 8MB per file. + image_file: + type: string + description: | + The local path to the original image file uploaded to BigCommerce. A `multipart/form-data` media type. + + Must be sent as a `multipart/form-data` field in the request body. Limit of 8 MB per file. + multipart/form-data: + schema: + title: Product Image Post + description: The model for a POST to create an image on a product. + allOf: + - title: Product Image Base + type: object + properties: + id: + type: integer + description: | + The unique numeric ID of the image; increments sequentially. + product_id: + type: integer + description: | + The unique numeric identifier for the product with which the image is associated. + url_zoom: + readOnly: true + type: string + description: | + The zoom URL for this image. By default, this is used as the zoom image on product pages when zoom images are enabled. + url_standard: + readOnly: true + type: string + description: | + The standard URL for this image. By default, this is used for product-page images. + url_thumbnail: + readOnly: true + type: string + description: | + The thumbnail URL for this image. By default, this is the image size used on the category page and in side panels. + url_tiny: + readOnly: true + type: string + description: | + The tiny URL for this image. By default, this is the image size used for thumbnails beneath the product image on a product page. + date_modified: + type: string + description: | + The date on which the product image was modified. + format: date-time + is_thumbnail: + type: boolean + description: | + Flag for identifying whether the image is used as the product's thumbnail. + sort_order: + maximum: 2147483647 + minimum: -2147483648 + type: integer + description: | + The order in which the image will be displayed on the product page. Higher integers give the image a lower priority. When updating, if the image is given a lower priority, all images with a `sort_order` the same as or greater than the image's new `sort_order` value will have their `sort_order`s reordered. + description: + type: string + description: | + The description for the image. + description: Common ProductImage properties. + - type: object + properties: + image_url: + type: string + description: | + Must be a fully qualified URL path, including protocol. Limit of 8MB per file. + image_file: + type: string + description: | + The local path to the original image file uploaded to BigCommerce. A `multipart/form-data` media type. + + Must be sent as a multipart/form-data field in the request body. Limit of 8 MB per file. + required: true + responses: + '200': + description: Success + content: + application/json: + schema: + title: Product Image Response + type: object + properties: + data: + title: Product Image + type: object + allOf: + - title: Product Image Base + type: object + properties: + id: + type: integer + description: | + The unique numeric ID of the image; increments sequentially. + product_id: + type: integer + description: | + The unique numeric identifier for the product with which the image is associated. + url_zoom: + readOnly: true + type: string + description: | + The zoom URL for this image. By default, this is used as the zoom image on product pages when zoom images are enabled. + url_standard: + readOnly: true + type: string + description: | + The standard URL for this image. By default, this is used for product-page images. + url_thumbnail: + readOnly: true + type: string + description: | + The thumbnail URL for this image. By default, this is the image size used on the category page and in side panels. + url_tiny: + readOnly: true + type: string + description: | + The tiny URL for this image. By default, this is the image size used for thumbnails beneath the product image on a product page. + date_modified: + type: string + description: | + The date on which the product image was modified. + format: date-time + is_thumbnail: + type: boolean + description: | + Flag for identifying whether the image is used as the product's thumbnail. + sort_order: + maximum: 2147483647 + minimum: -2147483648 + type: integer + description: | + The order in which the image will be displayed on the product page. Higher integers give the image a lower priority. When updating, if the image is given a lower priority, all images with a `sort_order` the same as or greater than the image's new `sort_order` value will have their `sort_order`s reordered. + description: + type: string + description: | + The description for the image. + description: Common ProductImage properties. + - type: object + properties: + id: + type: integer + description: | + The unique numeric ID of the image; increments sequentially. + product_id: + type: integer + description: | + The unique numeric identifier for the product with which the image is associated. + image_file: + type: string + description: |- + The local path to the original image file uploaded to BigCommerce. Use image_url when creating a product. + A `multipart/form-data` media type. + + Must be sent as a multipart/form-data field in the request body. Limit of 8 MB per file. + url_zoom: + readOnly: true + type: string + description: | + The zoom URL for this image. By default, this is used as the zoom image on product pages when zoom images are enabled. + url_standard: + readOnly: true + type: string + description: | + The standard URL for this image. By default, this is used for product-page images. + url_thumbnail: + readOnly: true + type: string + description: | + The thumbnail URL for this image. By default, this is the image size used on the category page and in side panels. + url_tiny: + readOnly: true + type: string + description: | + The tiny URL for this image. By default, this is the image size used for thumbnails beneath the product image on a product page. + date_modified: + type: string + description: | + The date on which the product image was modified. + format: date-time + image_url: + type: string + description: |- + Publically available URL. + Use the image_url when creating a product. + example: 'https://upload.wikimedia.org/wikipedia/commons/7/7f/Anglel_Bless_Legendary_Hills_1_m%C4%9Bs%C3%ADc_st%C3%A1%C5%99%C3%AD.jpg' + meta: + $ref: '#/components/schemas/metaEmpty_Full' + description: | + Response payload for the BigCommerce API. + example: + data: + id: 485 + product_id: 158 + is_thumbnail: false + sort_order: 1 + description: '' + image_file: o/381/product-image__98178.png + url_zoom: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/485/product-image__98178.1536854227.1280.1280.png?c=2' + url_standard: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/485/product-image__98178.1536854227.560.850.png?c=2' + url_thumbnail: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/485/product-image__98178.1536854227.330.500.png?c=2' + url_tiny: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/485/product-image__98178.1536854227.66.100.png?c=2' + date_modified: '2018-09-13T15:57:07+00:00' + meta: {} + '400': + description: Bad Request. The requested resource could not be downloaded and may be invalid. Possible reasons include malformed request syntax or the file host blocking requests. + content: + application/json: + schema: + type: object + properties: {} + '404': + description: | + The product ID does not exist. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + '422': + description: |- + Unprocessable Entity. + + May occur if the `Content-Type` header is set to `multipart/form-data` rather than `application/json` when creating a product image using `image_url`. + content: + application/json: + schema: + required: + - status + - title + - type + type: object + properties: + status: + type: number + title: + minLength: 1 + type: string + type: + minLength: 1 + type: string + description: '' + example: + status: 422 + title: image_url must be present if uploading by url + type: /api-docs/getting-started/api-status-codes + x-codegen-request-body-name: productImage + parameters: + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/ProductIdParam' + '/catalog/products/{product_id}/images/{image_id}': + get: + tags: + - Images + summary: Get a Product Image + description: Returns a single *Product Image*. Optional parameters can be passed in. + operationId: getProductImageById + parameters: + - name: include_fields + in: query + description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' + schema: + type: string + - name: exclude_fields + in: query + description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + title: Product Image Response + type: object + properties: + data: + $ref: '#/components/schemas/productImage_Full' + meta: + $ref: '#/components/schemas/metaEmpty_Full' + description: | + Response payload for the BigCommerce API. + example: + data: + id: 485 + product_id: 158 + is_thumbnail: false + sort_order: 1 + description: '' + image_file: o/381/product-image__98178.png + url_zoom: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/485/product-image__98178.1536854227.1280.1280.png?c=2' + url_standard: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/485/product-image__98178.1536854227.560.850.png?c=2' + url_thumbnail: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/485/product-image__98178.1536854227.330.500.png?c=2' + url_tiny: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/485/product-image__98178.1536854227.66.100.png?c=2' + date_modified: '2018-09-13T15:57:07+00:00' + meta: {} + '404': + description: | + The resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + put: + tags: + - Images + summary: Update a Product Image + description: |- + Updates a *Product Image*. + + **Usage Notes** + - `image_url` - `255` character limit + - Each image file or image uploaded by URL can be up to 8 MB. + - For file uploads, send a POST request using the `multipart/form-data` media type + operationId: updateProductImage + parameters: + - $ref: '#/components/parameters/ContentType' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/productImage_Put' + required: true + responses: + '200': + description: '' + content: + application/json: + schema: + title: Product Image Response + type: object + properties: + data: + title: Product Image + type: object + allOf: + - title: Product Image Base + type: object + properties: + id: + type: integer + description: | + The unique numeric ID of the image; increments sequentially. + product_id: + type: integer + description: | + The unique numeric identifier for the product with which the image is associated. + url_zoom: + readOnly: true + type: string + description: | + The zoom URL for this image. By default, this is used as the zoom image on product pages when zoom images are enabled. + url_standard: + readOnly: true + type: string + description: | + The standard URL for this image. By default, this is used for product-page images. + url_thumbnail: + readOnly: true + type: string + description: | + The thumbnail URL for this image. By default, this is the image size used on the category page and in side panels. + url_tiny: + readOnly: true + type: string + description: | + The tiny URL for this image. By default, this is the image size used for thumbnails beneath the product image on a product page. + date_modified: + type: string + description: | + The date on which the product image was modified. + format: date-time + is_thumbnail: + type: boolean + description: | + Flag for identifying whether the image is used as the product's thumbnail. + sort_order: + maximum: 2147483647 + minimum: -2147483648 + type: integer + description: | + The order in which the image will be displayed on the product page. Higher integers give the image a lower priority. When updating, if the image is given a lower priority, all images with a `sort_order` the same as or greater than the image's new `sort_order` value will have their `sort_order`s reordered. + description: + type: string + description: | + The description for the image. + description: Common ProductImage properties. + - type: object + properties: + id: + type: integer + description: | + The unique numeric ID of the image; increments sequentially. + product_id: + type: integer + description: | + The unique numeric identifier for the product with which the image is associated. + image_file: + type: string + description: | + The local path to the original image file uploaded to BigCommerce. Use image_url when creating a product. + + Must be sent as a `multipart/form-data` field in the request body. Limit of 8 MB per file. + url_zoom: + readOnly: true + type: string + description: | + The zoom URL for this image. By default, this is used as the zoom image on product pages when zoom images are enabled. + url_standard: + readOnly: true + type: string + description: | + The standard URL for this image. By default, this is used for product-page images. + url_thumbnail: + readOnly: true + type: string + description: | + The thumbnail URL for this image. By default, this is the image size used on the category page and in side panels. + url_tiny: + readOnly: true + type: string + description: | + The tiny URL for this image. By default, this is the image size used for thumbnails beneath the product image on a product page. + date_modified: + type: string + description: | + The date on which the product image was modified. + format: date-time + image_url: + type: string + description: |- + Publically available URL. + Use the image_url when creating a product. + example: 'https://upload.wikimedia.org/wikipedia/commons/7/7f/Anglel_Bless_Legendary_Hills_1_m%C4%9Bs%C3%ADc_st%C3%A1%C5%99%C3%AD.jpg' + meta: + $ref: '#/components/schemas/metaEmpty_Full' + description: | + Response payload for the BigCommerce API. + example: + data: + id: 485 + product_id: 158 + is_thumbnail: false + sort_order: 1 + description: '' + image_file: o/381/product-image__98178.png + url_zoom: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/485/product-image__98178.1536854227.1280.1280.png?c=2' + url_standard: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/485/product-image__98178.1536854227.560.850.png?c=2' + url_thumbnail: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/485/product-image__98178.1536854227.330.500.png?c=2' + url_tiny: 'https://cdn8.bigcommerce.com/s-id30h7ohwf/products/158/images/485/product-image__98178.1536854227.66.100.png?c=2' + date_modified: '2018-09-13T15:57:07+00:00' + meta: {} + '201': + description: Created + content: + application/json: + schema: + type: object + properties: {} + '400': + description: Bad Request. The requested resource could not be downloaded and may be invalid. Possible reasons include malformed request syntax or the file host blocking requests. + content: + application/json: + schema: + type: object + properties: {} + '404': + description: | + The resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + x-codegen-request-body-name: productImage + delete: + tags: + - Images + summary: Delete a Product Image + description: Deletes a *Product Image*. + operationId: deleteProductImage + responses: + '204': + description: '' + content: {} + parameters: + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/ProductIdParam' + - $ref: '#/components/parameters/ImageIdParam' + '/catalog/products/{product_id}/videos': + get: + tags: + - Videos + summary: Get All Product Videos + description: Returns a list of *Product Videos*. Optional parameters can be passed in. + operationId: getProductVideos + parameters: + - name: include_fields + in: query + description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' + schema: + type: string + - name: exclude_fields + in: query + description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' + schema: + type: string + - name: page + in: query + description: Specifies the page number in a limited (paginated) list of products. + schema: + type: integer + - name: limit + in: query + description: Controls the number of items per page in a limited (paginated) list of products. + schema: + type: integer + responses: + '200': + description: '' + content: + application/json: + schema: + title: Product Video Collection Response + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/productVideo_Full' + meta: + $ref: '#/components/schemas/metaCollection_Full' + example: + data: + - id: 6 + type: youtube + video_id: PqBTp23RLhI + product_id: 192 + sort_order: 1 + title: Creating and Editing Banners | BigCommerce Tutorials + description: 'Learn how to create and edit marketing banners. Marketing banners are a great way to advertise sales, display coupon codes, and add design elements. Let’s take a look at how you can leverage banners to convert your store’s visitors into paying customers.' + length: '01:54' + - id: 7 + type: youtube + video_id: EhYBjzqd-nI + product_id: 192 + sort_order: 2 + title: BigCommerce Company Values + description: |- + These are the core principles upon which BigCommerce was built, guiding what we do and how we do it. Each employee learns them, loves them and lives them. Our merchants benefit from them every time they use our product or get help from our support team. + + Join the BigCommerce team and help us build software that changes lives! + + https://www.bigcommerce.com/careers/ + length: '03:30' + - id: 8 + type: youtube + video_id: vAUdo4kRjrU + product_id: 192 + sort_order: 3 + title: TOP WORKPLACES 2016 - Austin American Statesman + BigCommerce + description: |- + We've been named one of Austin American-Statesman's Top WorkPlaces for the 5th year in a row! Here's what some employees have to say: + + “I am given the freedom and trust to make a difference.” + + “Everyone believes in the product and growing the company.” + + “I'm appreciated for the work I do and there is room to grown within the company.” + + Work With Us! + http://www.bigcommerce.com/careers.php + length: '01:37' + meta: + pagination: + total: 3 + count: 3 + per_page: 50 + current_page: 1 + total_pages: 1 + links: + current: '?page=1&limit=50' + post: + tags: + - Videos + summary: Create a Product Video + description: |- + Creates a *Product Video*. + + **Required Fields** + * video_id + + **Read-Only Fields** + * id + + Publicly accessible URLs are valid parameters. + Videos must be loaded through YouTube at this time. + operationId: createProductVideo + parameters: + - $ref: '#/components/parameters/ContentType' + requestBody: + content: + application/json: + schema: + title: Product Video Post + description: | + The model for a POST to create a video on a product. + allOf: + - title: Product Video Base + description: Common Product Video properties. + properties: + title: + maxLength: 255 + minLength: 0 + type: string + example: Writing Great Documentation + description: | + The title for the video. If left blank, this will be filled in according to data on a host site. + description: + type: string + example: A video about documenation + description: | + The description for the video. If left blank, this will be filled in according to data on a host site. + sort_order: + maximum: 2147483647 + minimum: -2147483648 + example: 1 + type: integer + description: | + The order in which the video will be displayed on the product page. Higher integers give the video a lower priority. When updating, if the video is given a lower priority, all videos with a `sort_order` the same as or greater than the video's new `sort_order` value will have their `sort_order`s reordered. + type: + type: string + description: | + The video type (a short name of a host site). + enum: + - youtube + - properties: + video_id: + type: string + maxLength: 25 + minLength: 0 + description: | + The ID of the video on a host site. + x-required: + - post + example: z3fRu9pkuXE + type: object + required: true + responses: + '200': + description: '' + content: + application/json: + schema: + title: Product Video Response + type: object + properties: + data: + title: Product Video + type: object + description: | + A product video model. + allOf: + - title: Product Video Base + type: object + properties: + title: + maxLength: 255 + minLength: 0 + type: string + description: | + The title for the video. If left blank, this will be filled in according to data on a host site. + description: + type: string + description: | + The description for the video. If left blank, this will be filled in according to data on a host site. + sort_order: + maximum: 2147483647 + minimum: -2147483648 + type: integer + description: | + The order in which the video will be displayed on the product page. Higher integers give the video a lower priority. When updating, if the video is given a lower priority, all videos with a `sort_order` the same as or greater than the video's new `sort_order` value will have their `sort_order`s reordered. + type: + type: string + description: | + The video type (a short name of a host site). + enum: + - youtube + description: Common Product Video properties. + - type: object + properties: + id: + type: integer + description: | + The unique numeric ID of the product video; increments sequentially. + video_id: + type: string + description: | + The ID of the video on a host site. + product_id: + type: integer + description: | + The unique numeric identifier for the product with which the image is associated. + length: + type: string + description: | + Length of the video. This will be filled in according to data on a host site. + meta: + $ref: '#/components/schemas/metaEmpty_Full' + description: | + Response payload for the BigCommerce API. + example: + title: Your Video + description: Company Values + sort_order: 1 + type: youtube + video_id: 123345AA + '404': + description: | + The resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + x-codegen-request-body-name: productVideo + parameters: + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/ProductIdParam' + '/catalog/products/{product_id}/videos/{id}': + get: + tags: + - Videos + summary: Get a Product Video + description: Returns a single *Product Video*. Optional parameters can be passed in. + operationId: getProductVideoById + parameters: + - name: include_fields + in: query + description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' + schema: + type: string + - name: exclude_fields + in: query + description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + title: Product Video Response + type: object + properties: + data: + $ref: '#/components/schemas/productVideo_Full' + meta: + $ref: '#/components/schemas/metaEmpty_Full' + description: | + Response payload for the BigCommerce API. + example: + title: Your Video + description: Company Values + sort_order: 1 + type: youtube + video_id: 123345AA + '404': + description: | + The resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + put: + tags: + - Videos + summary: Update a Product Video + description: |- + Updates a *Product Video. + + **Required Fields** + * none + + **Read-Only Fields** + * id + operationId: updateProductVideo + parameters: + - $ref: '#/components/parameters/ContentType' + requestBody: + content: + application/json: + schema: + title: Product Video Put + description: | + The model for a PUT to update a video on a product. + allOf: + - title: Product Video Base + type: object + properties: + title: + maxLength: 255 + minLength: 0 + type: string + description: | + The title for the video. If left blank, this will be filled in according to data on a host site. + description: + type: string + description: | + The description for the video. If left blank, this will be filled in according to data on a host site. + sort_order: + maximum: 2147483647 + minimum: -2147483648 + type: integer + description: | + The order in which the video will be displayed on the product page. Higher integers give the video a lower priority. When updating, if the video is given a lower priority, all videos with a `sort_order` the same as or greater than the video's new `sort_order` value will have their `sort_order`s reordered. + type: + type: string + description: | + The video type (a short name of a host site). + enum: + - youtube + description: Common Product Video properties. + - type: object + properties: + id: + type: integer + description: | + The unique numeric ID of the product video; increments sequentially. + x-required: + - put + required: true + responses: + '200': + description: '' + content: + application/json: + schema: + title: Product Video Response + type: object + properties: + data: + title: Product Video + type: object + description: | + A product video model. + allOf: + - title: Product Video Base + type: object + properties: + title: + maxLength: 255 + minLength: 0 + type: string + description: | + The title for the video. If left blank, this will be filled in according to data on a host site. + description: + type: string + description: | + The description for the video. If left blank, this will be filled in according to data on a host site. + sort_order: + maximum: 2147483647 + minimum: -2147483648 + type: integer + description: | + The order in which the video will be displayed on the product page. Higher integers give the video a lower priority. When updating, if the video is given a lower priority, all videos with a `sort_order` the same as or greater than the video's new `sort_order` value will have their `sort_order`s reordered. + type: + type: string + description: | + The video type (a short name of a host site). + enum: + - youtube + description: Common Product Video properties. + - type: object + properties: + id: + type: integer + description: | + The unique numeric ID of the product video; increments sequentially. + video_id: + type: string + description: | + The ID of the video on a host site. + product_id: + type: integer + description: | + The unique numeric identifier for the product with which the image is associated. + length: + type: string + description: | + Length of the video. This will be filled in according to data on a host site. + meta: + $ref: '#/components/schemas/metaEmpty_Full' + description: | + Response payload for the BigCommerce API. + example: + title: Your Video + description: Company Values + sort_order: 1 + type: youtube + video_id: 123345AA + '404': + description: | + The resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + x-codegen-request-body-name: productVideo + delete: + tags: + - Videos + summary: Delete a Product Video + description: Deletes a *Product Video*. + operationId: deleteProductVideo + responses: + '204': + description: '' + content: {} + parameters: + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/ProductIdParam' + - $ref: '#/components/parameters/VideoIdParam' + '/catalog/products/{product_id}/complex-rules': + get: + tags: + - Complex Rules + summary: Get Complex Rules + description: Returns a list of all product *Complex Rules*. Optional parameters may be passed in. + operationId: getComplexRules + parameters: + - name: include_fields + in: query + description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' + schema: + type: string + - name: exclude_fields + in: query + description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' + schema: + type: string + - name: page + in: query + description: Specifies the page number in a limited (paginated) list of products. + schema: + type: integer + - name: limit + in: query + description: Controls the number of items per page in a limited (paginated) list of products. + schema: + type: integer + responses: + '200': + description: '' + content: + application/json: + schema: + title: Complex Rule Collection Response + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/complexRule_Base' + meta: + $ref: '#/components/schemas/metaCollection_Full' + description: Complex Rule Response + example: + data: + - id: 82 + product_id: 195 + sort_order: 0 + enabled: true + stop: false + price_adjuster: + adjuster: relative + adjuster_value: 8 + weight_adjuster: {} + purchasing_disabled: false + purchasing_disabled_message: '' + purchasing_hidden: false + image_url: '' + conditions: + - rule_id: 82 + modifier_id: 221 + modifier_value_id: 175 + variant_id: 1 + combination_id: 0 + - id: 83 + product_id: 195 + sort_order: 1 + enabled: true + stop: false + price_adjuster: {} + weight_adjuster: + adjuster: relative + adjuster_value: 3 + purchasing_disabled: false + purchasing_disabled_message: '' + purchasing_hidden: false + image_url: '' + conditions: + - rule_id: 83 + modifier_id: 221 + modifier_value_id: 174 + variant_id: 1 + combination_id: 0 + meta: + pagination: + total: 2 + count: 2 + per_page: 50 + current_page: 1 + total_pages: 1 + links: + current: '?page=1&limit=50' + post: + tags: + - Complex Rules + summary: Create a Complex Rule + description: |- + Creates a product *Complex Rule*. + + **Required Fields** + - modifier_id + - modifier_value_id + - variant_id + + **Read-Only Fields** + - complex_rule_id + - conditions_id + - rule_id + - combination_id + - id + operationId: createComplexRule + parameters: + - $ref: '#/components/parameters/ContentType' + requestBody: + content: + application/json: + schema: + title: Complex Rule + type: object + properties: + product_id: + type: integer + description: | + The unique numeric ID of the product with which the rule is associated; increments sequentially. + nullable: true + example: 67 + x-required: + - post + - put + sort_order: + maximum: 2147483647 + minimum: -2147483648 + type: integer + description: | + The priority to give this rule when making adjustments to the product properties. + example: 0 + enabled: + type: boolean + description: | + Flag for determining whether the rule is to be used when adjusting a product's price, weight, image, or availabilty. + example: true + stop: + type: boolean + description: | + Flag for determining whether other rules should not be applied after this rule has been applied. + purchasing_disabled: + type: boolean + description: | + Flag for determining whether the rule should disable purchasing of a product when the conditions are applied. + purchasing_disabled_message: + maxLength: 255 + minLength: 0 + type: string + description: | + Message displayed on the storefront when a rule disables the purchasing of a product. + example: This product is not available at this time. + purchasing_hidden: + type: boolean + description: | + Flag for determining whether the rule should hide purchasing of a product when the conditions are applied. + image_url: + type: string + description: | + The URL for an image displayed on the storefront when the conditions are applied. Limit of 8MB per file. + example: 'https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png' + price_adjuster: + title: Adjuster + type: object + properties: + adjuster: + type: string + description: | + The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. + nullable: true + enum: + - relative + - percentage + adjuster_value: + type: number + description: | + The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. + example: 5 + description: Adjuster for Complex Rules. + weight_adjuster: + title: Adjuster + type: object + properties: + adjuster: + type: string + description: | + The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. + nullable: true + enum: + - relative + - percentage + adjuster_value: + type: number + description: | + The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. + example: 5 + description: Adjuster for Complex Rules. + conditions: + type: array + items: + title: Complex Rule Condition + required: + - modifier_id + - modifier_value_id + - variant_id + type: object + properties: + modifier_id: + type: integer + description: |- + The unique numeric ID of the modifier with which the rule condition is associated. + Required in /POST. + nullable: true + example: 55 + modifier_value_id: + type: integer + description: |- + The unique numeric ID of the modifier value with which the rule condition is associated. + Required in /POST. + nullable: true + example: 256 + variant_id: + type: integer + description: |- + The unique numeric ID of the variant with which the rule condition is associated. + Required in /POST. + nullable: true + example: 1 + description: Common ComplexRule properties. + required: true + responses: + '200': + description: '' + content: + application/json: + schema: + type: object + properties: + data: + title: Complex Rule + type: object + properties: + id: + type: integer + description: |- + The unique numeric ID of the rule; increments sequentially. + Read-Only + example: 5 + product_id: + type: integer + description: | + The unique numeric ID of the product with which the rule is associated; increments sequentially. + nullable: true + example: 67 + x-required: + - post + - put + sort_order: + maximum: 2147483647 + minimum: -2147483648 + type: integer + description: | + The priority to give this rule when making adjustments to the product properties. + example: 0 + enabled: + type: boolean + description: | + Flag for determining whether the rule is to be used when adjusting a product's price, weight, image, or availabilty. + example: true + stop: + type: boolean + description: | + Flag for determining whether other rules should not be applied after this rule has been applied. + purchasing_disabled: + type: boolean + description: | + Flag for determining whether the rule should disable purchasing of a product when the conditions are applied. + purchasing_disabled_message: + maxLength: 255 + minLength: 0 + type: string + description: | + Message displayed on the storefront when a rule disables the purchasing of a product. + example: This product is not available at this time. + purchasing_hidden: + type: boolean + description: | + Flag for determining whether the rule should hide purchasing of a product when the conditions are applied. + image_url: + type: string + description: | + The URL for an image displayed on the storefront when the conditions are applied. Limit of 8MB per file. + example: 'https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png' + price_adjuster: + title: Adjuster + type: object + properties: + adjuster: + type: string + description: | + The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. + nullable: true + enum: + - relative + - percentage + adjuster_value: + type: number + description: | + The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. + example: 5 + description: Adjuster for Complex Rules. + weight_adjuster: + title: Adjuster + type: object + properties: + adjuster: + type: string + description: | + The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. + nullable: true + enum: + - relative + - percentage + adjuster_value: + type: number + description: | + The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. + example: 5 + description: Adjuster for Complex Rules. + conditions: + type: array + items: + title: Complex Rule Condition + required: + - modifier_id + - modifier_value_id + - variant_id + type: object + properties: + id: + type: integer + description: | + The unique numeric ID of the rule condition; increments sequentially. Read-Only + nullable: true + example: 3 + rule_id: + type: integer + description: |- + The unique numeric ID of the rule with which the condition is associated. + Read-Only + nullable: true + example: 4 + modifier_id: + type: integer + description: |- + The unique numeric ID of the modifier with which the rule condition is associated. + Required in /POST. + nullable: true + example: 55 + modifier_value_id: + type: integer + description: |- + The unique numeric ID of the modifier value with which the rule condition is associated. + Required in /POST. + nullable: true + example: 256 + variant_id: + type: integer + description: |- + The unique numeric ID of the variant with which the rule condition is associated. + Required in /POST. + nullable: true + example: 1 + combination_id: + type: integer + description: | + (READ-ONLY:) The unique numeric ID of the SKU (v2 API), or Combination, with which the rule condition is associated. This is to maintain cross-compatibility between v2 and v3. + description: 'Complex rules may return with conditions that apply to one or more variants, or with a single modifier value (if the rules were created using the v2 API or the control panel). Complex rules created or updated in the v3 API must have conditions that either reference multiple `modifier_value_id`’s, or else reference a `modifier_value_id` and a `variant_id`.' + description: Common ComplexRule properties. + meta: + $ref: '#/components/schemas/metaEmpty_Full' + '409': + description: | + The `ComplexRule` was in conflict with another `ComplexRule`. This is the result of duplicate conditions. + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + '422': + description: | + The `ComplexRule` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + x-codegen-request-body-name: ComplexRule + parameters: + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/ProductIdParam' + '/catalog/products/{product_id}/complex-rules/{complex_rule_id}': + get: + tags: + - Complex Rules + summary: Get a Complex Rule + description: Returns a single *Complex Rule*. Optional parameters can be passed in. + operationId: getComplexRuleById + parameters: + - name: include_fields + in: query + description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' + schema: + type: string + - name: exclude_fields + in: query + description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + type: object + properties: + data: + title: Complex Rule + type: object + properties: + id: + type: integer + description: |- + The unique numeric ID of the rule; increments sequentially. + Read-Only + example: 5 + product_id: + type: integer + description: | + The unique numeric ID of the product with which the rule is associated; increments sequentially. + example: 67 + x-required: + - post + - put + sort_order: + maximum: 2147483647 + minimum: -2147483648 + type: integer + description: | + The priority to give this rule when making adjustments to the product properties. + example: 0 + enabled: + type: boolean + description: | + Flag for determining whether the rule is to be used when adjusting a product's price, weight, image, or availabilty. + example: true + stop: + type: boolean + description: | + Flag for determining whether other rules should not be applied after this rule has been applied. + purchasing_disabled: + type: boolean + description: | + Flag for determining whether the rule should disable purchasing of a product when the conditions are applied. + purchasing_disabled_message: + maxLength: 255 + minLength: 0 + type: string + description: | + Message displayed on the storefront when a rule disables the purchasing of a product. + example: This product is not available at this time. + purchasing_hidden: + type: boolean + description: | + Flag for determining whether the rule should hide purchasing of a product when the conditions are applied. + image_url: + type: string + description: | + The URL for an image displayed on the storefront when the conditions are applied. Limit of 8MB per file. + example: 'https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png' + price_adjuster: + title: Adjuster + type: object + properties: + adjuster: + type: string + description: | + The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. + enum: + - relative + - percentage + adjuster_value: + type: number + description: | + The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. + example: 5 + description: Adjuster for Complex Rules. + weight_adjuster: + title: Adjuster + type: object + properties: + adjuster: + type: string + description: | + The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. + enum: + - relative + - percentage + adjuster_value: + type: number + description: | + The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. + example: 5 + description: Adjuster for Complex Rules. + conditions: + type: array + items: + title: Complex Rule Condition + required: + - modifier_id + - modifier_value_id + - variant_id + type: object + properties: + id: + type: integer + description: | + The unique numeric ID of the rule condition; increments sequentially. Read-Only + example: 3 + rule_id: + type: integer + description: |- + The unique numeric ID of the rule with which the condition is associated. + Read-Only + example: 4 + modifier_id: + type: integer + description: |- + The unique numeric ID of the modifier with which the rule condition is associated. + Required in /POST. + example: 55 + modifier_value_id: + type: integer + description: |- + The unique numeric ID of the modifier value with which the rule condition is associated. + Required in /POST. + example: 256 + variant_id: + type: integer + description: |- + The unique numeric ID of the variant with which the rule condition is associated. + Required in /POST. + example: 1 + combination_id: + type: integer + description: | + (READ-ONLY:) The unique numeric ID of the SKU (v2 API), or Combination, with which the rule condition is associated. This is to maintain cross-compatibility between v2 and v3. + description: 'Complex rules may return with conditions that apply to one or more variants, or with a single modifier value (if the rules were created using the v2 API or the control panel). Complex rules created or updated in the v3 API must have conditions that either reference multiple `modifier_value_id`’s, or else reference a `modifier_value_id` and a `variant_id`.' + description: Common ComplexRule properties. + meta: + $ref: '#/components/schemas/metaEmpty_Full' + '404': + description: | + The resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + put: + tags: + - Complex Rules + summary: Update a Complex Rule + description: |- + Updates a *Complex Rule*. + + **Required Fields**: + - none + + **Read-Only Fields**: + - complex_rule_id + - conditions_id + - rule_id + - combination_id + - id + operationId: updateComplexRule + parameters: + - $ref: '#/components/parameters/ContentType' + requestBody: + content: + application/json: + schema: + title: Complex Rule + type: object + properties: + product_id: + type: integer + description: | + The unique numeric ID of the product with which the rule is associated; increments sequentially. + nullable: true + example: 67 + x-required: + - post + - put + sort_order: + maximum: 2147483647 + minimum: -2147483648 + type: integer + description: | + The priority to give this rule when making adjustments to the product properties. + example: 0 + enabled: + type: boolean + description: | + Flag for determining whether the rule is to be used when adjusting a product's price, weight, image, or availabilty. + example: true + stop: + type: boolean + description: | + Flag for determining whether other rules should not be applied after this rule has been applied. + purchasing_disabled: + type: boolean + description: | + Flag for determining whether the rule should disable purchasing of a product when the conditions are applied. + purchasing_disabled_message: + maxLength: 255 + minLength: 0 + type: string + description: | + Message displayed on the storefront when a rule disables the purchasing of a product. + example: This product is not available at this time. + purchasing_hidden: + type: boolean + description: | + Flag for determining whether the rule should hide purchasing of a product when the conditions are applied. + image_url: + type: string + description: | + The URL for an image displayed on the storefront when the conditions are applied. Limit of 8MB per file. + example: 'https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png' + price_adjuster: + title: Adjuster + type: object + properties: + adjuster: + type: string + description: | + The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. + nullable: true + enum: + - relative + - percentage + adjuster_value: + type: number + description: | + The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. + example: 5 + description: Adjuster for Complex Rules. + weight_adjuster: + title: Adjuster + type: object + properties: + adjuster: + type: string + description: | + The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. + nullable: true + enum: + - relative + - percentage + adjuster_value: + type: number + description: | + The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. + example: 5 + description: Adjuster for Complex Rules. + conditions: + type: array + items: + title: Complex Rule Condition + required: + - modifier_id + - modifier_value_id + - variant_id + type: object + properties: + modifier_id: + type: integer + description: |- + The unique numeric ID of the modifier with which the rule condition is associated. + Required in /POST. + nullable: true + example: 55 + modifier_value_id: + type: integer + description: |- + The unique numeric ID of the modifier value with which the rule condition is associated. + Required in /POST. + nullable: true + example: 256 + variant_id: + type: integer + description: |- + The unique numeric ID of the variant with which the rule condition is associated. + Required in /POST. + nullable: true + example: 1 + description: Common ComplexRule properties. + required: true + responses: + '200': + description: '' + content: + application/json: + schema: + type: object + properties: + data: + title: Complex Rule + type: object + properties: + id: + type: integer + description: |- + The unique numeric ID of the rule; increments sequentially. + Read-Only + example: 5 + product_id: + type: integer + description: | + The unique numeric ID of the product with which the rule is associated; increments sequentially. + example: 67 + x-required: + - post + - put + sort_order: + maximum: 2147483647 + minimum: -2147483648 + type: integer + description: | + The priority to give this rule when making adjustments to the product properties. + example: 0 + enabled: + type: boolean + description: | + Flag for determining whether the rule is to be used when adjusting a product's price, weight, image, or availabilty. + example: true + stop: + type: boolean + description: | + Flag for determining whether other rules should not be applied after this rule has been applied. + purchasing_disabled: + type: boolean + description: | + Flag for determining whether the rule should disable purchasing of a product when the conditions are applied. + purchasing_disabled_message: + maxLength: 255 + minLength: 0 + type: string + description: | + Message displayed on the storefront when a rule disables the purchasing of a product. + example: This product is not available at this time. + purchasing_hidden: + type: boolean + description: | + Flag for determining whether the rule should hide purchasing of a product when the conditions are applied. + image_url: + type: string + description: | + The URL for an image displayed on the storefront when the conditions are applied. Limit of 8MB per file. + example: 'https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png' + price_adjuster: + title: Adjuster + type: object + properties: + adjuster: + type: string + description: | + The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. + enum: + - relative + - percentage + adjuster_value: + type: number + description: | + The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. + example: 5 + description: Adjuster for Complex Rules. + weight_adjuster: + title: Adjuster + type: object + properties: + adjuster: + type: string + description: | + The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. + enum: + - relative + - percentage + adjuster_value: + type: number + description: | + The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. + example: 5 + description: Adjuster for Complex Rules. + conditions: + type: array + items: + title: Complex Rule Condition + required: + - modifier_id + - modifier_value_id + - variant_id + type: object + properties: + id: + type: integer + description: | + The unique numeric ID of the rule condition; increments sequentially. Read-Only + example: 3 + rule_id: + type: integer + description: |- + The unique numeric ID of the rule with which the condition is associated. + Read-Only + example: 4 + modifier_id: + type: integer + description: |- + The unique numeric ID of the modifier with which the rule condition is associated. + Required in /POST. + example: 55 + modifier_value_id: + type: integer + description: |- + The unique numeric ID of the modifier value with which the rule condition is associated. + Required in /POST. + example: 256 + variant_id: + type: integer + description: |- + The unique numeric ID of the variant with which the rule condition is associated. + Required in /POST. + example: 1 + combination_id: + type: integer + description: | + (READ-ONLY:) The unique numeric ID of the SKU (v2 API), or Combination, with which the rule condition is associated. This is to maintain cross-compatibility between v2 and v3. + description: 'Complex rules may return with conditions that apply to one or more variants, or with a single modifier value (if the rules were created using the v2 API or the control panel). Complex rules created or updated in the v3 API must have conditions that either reference multiple `modifier_value_id`’s, or else reference a `modifier_value_id` and a `variant_id`.' + description: Common ComplexRule properties. + meta: + $ref: '#/components/schemas/metaEmpty_Full' + '409': + description: | + The `ComplexRule` was in conflict with another `ComplexRule`. This is the result of duplicate conditions. + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + '422': + description: | + The `ComplexRule` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + x-codegen-request-body-name: ComplexRule + delete: + tags: + - Complex Rules + summary: Delete a Complex Rule + description: Deletes a product *Complex Rule*. + operationId: deleteComplexRuleById + responses: + '204': + description: '' + content: {} + parameters: + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/ProductIdParam' + - $ref: '#/components/parameters/ComplexRuleIdParam' + '/catalog/products/{product_id}/custom-fields': + get: + tags: + - Custom Fields + summary: Get Custom Fields + description: |- + Returns a list of product *Custom Fields*. Optional parameters can be passed in. + + **Note:** + The default rate limit for this endpoint is 40 concurrent requests. + operationId: getCustomFields + parameters: + - name: include_fields + in: query + description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' + schema: + type: string + - name: exclude_fields + in: query + description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' + schema: + type: string + - name: page + in: query + description: Specifies the page number in a limited (paginated) list of products. + schema: + type: integer + - name: limit + in: query + description: Controls the number of items per page in a limited (paginated) list of products. + schema: + type: integer + responses: + '200': + description: '' + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + title: Custom Field + required: + - name + - value + type: object + properties: + id: + minimum: 1 + type: integer + description: |- + The unique numeric ID of the custom field; increments sequentially. + Read-Only + example: 6 + name: + maxLength: 250 + minLength: 1 + type: string + description: | + The name of the field, shown on the storefront, orders, etc. Required for /POST + example: ISBN + x-required: + - post + value: + maxLength: 250 + minLength: 1 + type: string + description: | + The name of the field, shown on the storefront, orders, etc. Required for /POST + example: '1234567890123' + x-required: + - post + description: 'Gets custom fields associated with a product. These allow you to specify additional information that will appear on the product’s page, such as a book’s ISBN or a DVD’s release date.' + meta: + $ref: '#/components/schemas/metaCollection_Full' + example: + data: + - name: Release year + value: '1987' + id: 1 + meta: + pagination: + total: 1 + count: 1 + per_page: 50 + current_page: 1 + total_pages: 1 + links: + previous: '?page=1&limit=50' + current: '?page=1&limit=50' + next: '?page=1&limit=50' + post: + tags: + - Custom Fields + summary: Create a Custom Fields + description: |- + Creates a *Custom Field*. + + **Required Fields:** + - name + - value + + **Read-Only:** + - id + + **Note:** + The default rate limit for this endpoint is 40 concurrent requests. + operationId: createCustomField + parameters: + - $ref: '#/components/parameters/ContentType' + requestBody: + content: + application/json: + schema: + title: Custom Field + required: + - name + - value + type: object + properties: + name: + maxLength: 250 + minLength: 1 + type: string + description: | + The name of the field, shown on the storefront, orders, etc. Required for /POST + example: ISBN + x-required: + - post + value: + maxLength: 250 + minLength: 1 + type: string + description: | + The name of the field, shown on the storefront, orders, etc. Required for /POST + example: '1234567890123' + x-required: + - post + description: 'Gets custom fields associated with a product. These allow you to specify additional information that will appear on the product’s page, such as a book’s ISBN or a DVD’s release date.' + required: true + responses: + '200': + description: '' + content: + application/json: + schema: + type: object + properties: + data: + title: Custom Field + required: + - name + - value + type: object + properties: + id: + minimum: 1 + type: integer + description: |- + The unique numeric ID of the custom field; increments sequentially. + Read-Only + example: 6 + name: + maxLength: 250 + minLength: 1 + type: string + description: | + The name of the field, shown on the storefront, orders, etc. Required for /POST + example: ISBN + x-required: + - post + value: + maxLength: 250 + minLength: 1 + type: string + description: | + The name of the field, shown on the storefront, orders, etc. Required for /POST + example: '1234567890123' + x-required: + - post + description: 'Gets custom fields associated with a product. These allow you to specify additional information that will appear on the product’s page, such as a book’s ISBN or a DVD’s release date.' + meta: + $ref: '#/components/schemas/metaEmpty_Full' + example: + data: + name: Release Year + value: '1976' + id: 2 + meta: {} + '404': + description: | + The parent resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + '422': + description: | + The `CustomField` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + x-codegen-request-body-name: CustomField + parameters: + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/ProductIdParam' + '/catalog/products/{product_id}/custom-fields/{custom_field_id}': + get: + tags: + - Custom Fields + summary: Get a Custom Field + description: Returns a single *Custom Field*. Optional parameters can be passed in. + operationId: getCustomFieldById + parameters: + - name: include_fields + in: query + description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' + schema: + type: string + - name: exclude_fields + in: query + description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/productCustomField_Base' + meta: + $ref: '#/components/schemas/metaEmpty_Full' + example: + data: + name: Release Year + value: '1976' + id: 2 + meta: {} + '404': + description: | + The resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + put: + tags: + - Custom Fields + summary: Update a Custom Field + description: |- + Updates a *Custom Field*. + + **Required Fields** + - none + + **Read-Only** + - id + operationId: updateCustomField + parameters: + - $ref: '#/components/parameters/ContentType' + requestBody: + content: + application/json: + schema: + title: Custom Field + required: + - name + - value + type: object + properties: + id: + minimum: 1 + type: integer + description: |- + The unique numeric ID of the custom field; increments sequentially. + Read-Only + example: 6 + name: + maxLength: 250 + minLength: 1 + type: string + description: | + The name of the field, shown on the storefront, orders, etc. Required for /POST + example: ISBN + x-required: + - post + value: + maxLength: 250 + minLength: 1 + type: string + description: | + The name of the field, shown on the storefront, orders, etc. Required for /POST + example: '1234567890123' + x-required: + - post + description: 'Gets custom fields associated with a product. These allow you to specify additional information that will appear on the product’s page, such as a book’s ISBN or a DVD’s release date.' + required: true + responses: + '200': + description: '' + content: + application/json: + schema: + type: object + properties: + data: + title: Custom Field + required: + - name + - value + type: object + properties: + id: + minimum: 1 + type: integer + description: |- + The unique numeric ID of the custom field; increments sequentially. + Read-Only + example: 6 + name: + maxLength: 250 + minLength: 1 + type: string + description: | + The name of the field, shown on the storefront, orders, etc. Required for /POST + example: ISBN + x-required: + - post + value: + maxLength: 250 + minLength: 1 + type: string + description: | + The name of the field, shown on the storefront, orders, etc. Required for /POST + example: '1234567890123' + x-required: + - post + description: 'Gets custom fields associated with a product. These allow you to specify additional information that will appear on the product’s page, such as a book’s ISBN or a DVD’s release date.' + meta: + $ref: '#/components/schemas/metaEmpty_Full' + example: + data: + name: Release Year + value: '1976' + id: 2 + meta: {} + '404': + description: | + The resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + '422': + description: | + The `CustomField` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + x-codegen-request-body-name: CustomField + delete: + tags: + - Custom Fields + summary: Delete a Custom Field + description: |- + Deletes a product *Custom Field*. + + **Note:** + The default rate limit for this endpoint is 40 concurrent requests. + operationId: deleteCustomFieldById + responses: + '204': + description: '`204 No Content`. Action has been enacted and no further information is to be supplied. `null` is returned.' + content: {} + '404': + description: | + The resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + parameters: + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/ProductIdParam' + - $ref: '#/components/parameters/CustomFieldIdParam' + '/catalog/products/{product_id}/bulk-pricing-rules': + get: + tags: + - Bulk Pricing Rules + summary: Get All Bulk Pricing Rules + description: Returns a list of *Bulk Pricing Rules*. Optional parameters can be passed in. + operationId: getBulkPricingRules + parameters: + - name: include_fields + in: query + description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' + schema: + type: string + - name: exclude_fields + in: query + description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' + schema: + type: string + - name: page + in: query + description: Specifies the page number in a limited (paginated) list of products. + schema: + type: integer + - name: limit + in: query + description: Controls the number of items per page in a limited (paginated) list of products. + schema: + type: integer + responses: + '200': + description: '' + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + allOf: + - type: object + properties: + id: + type: integer + description: Unique ID of the *Bulk Pricing Rule*. Read-Only. + readOnly: true + required: + - id + - $ref: '#/components/schemas/bulkPricingRule_Full' + meta: + $ref: '#/components/schemas/metaCollection_Full' + example: + data: + - id: 83 + quantity_min: 1 + quantity_max: 3 + type: price + amount: 1 + - id: 84 + quantity_min: 4 + quantity_max: 0 + type: price + amount: 1 + meta: + pagination: + total: 2 + count: 2 + per_page: 50 + current_page: 1 + total_pages: 1 + links: + current: '?page=1&limit=50' + '404': + description: | + The parent resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + post: + tags: + - Bulk Pricing Rules + summary: Create a Bulk Pricing Rule + description: |- + Creates a *Bulk Pricing Rule*. + + **Required Fields** + - quantity_min + - quantity_max + - type + - amount + + **Read-Only Fields** + - id + + **Limits** + - 50 bulk pricing rule per product limit. + operationId: createBulkPricingRule + parameters: + - $ref: '#/components/parameters/ContentType' + - name: page + in: query + description: Specifies the page number in a limited (paginated) list of products. + schema: + type: integer + - name: limit + in: query + description: Controls the number of items per page in a limited (paginated) list of products. + schema: + type: integer + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/bulkPricingRule_Full' + required: true + responses: + '200': + description: '' + content: + application/json: + schema: + type: object + properties: + data: + allOf: + - type: object + properties: + id: + type: integer + description: Unique ID of the *Bulk Pricing Rule*. Read-Only. + readOnly: true + required: + - id + - $ref: '#/components/schemas/bulkPricingRule_Full' + meta: + title: Meta + type: object + description: Empty meta object; may be used later. + example: + data: + id: 83 + quantity_min: 1 + quantity_max: 3 + type: price + amount: 1 + meta: {} + '404': + description: | + The parent resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + '409': + description: | + The `BulkPricingRule` was in conflict with another bulk pricing rule. This is the result of quantity range overlapping with existing bulk pricing rules. + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + '422': + description: | + The `BulkPricingRule` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + x-codegen-request-body-name: BulkPricingRule + parameters: + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/ProductIdParam' + '/catalog/products/{product_id}/bulk-pricing-rules/{bulk_pricing_rule_id}': + get: + tags: + - Bulk Pricing Rules + summary: Get a Bulk Pricing Rule + description: Returns a single *Bulk Pricing Rule*. Optional parameters can be passed in. + operationId: getBulkPricingRuleById + parameters: + - name: include_fields + in: query + description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' + schema: + type: string + - name: exclude_fields + in: query + description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + type: object + properties: + data: + allOf: + - type: object + properties: + id: + type: integer + description: Unique ID of the *Bulk Pricing Rule*. Read-Only. + readOnly: true + required: + - id + - $ref: '#/components/schemas/bulkPricingRule_Full' + meta: + $ref: '#/components/schemas/metaEmpty_Full' + example: + data: + id: 83 + quantity_min: 1 + quantity_max: 3 + type: price + amount: 1 + meta: {} + '404': + description: | + The resource or parent resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + put: + tags: + - Bulk Pricing Rules + summary: Update a Bulk Pricing Rule + description: |- + Updates a *Bulk Pricing Rule*. + + **Required Fields** + * none + + **Read-Only Fields** + - id + operationId: updateBulkPricingRule + parameters: + - $ref: '#/components/parameters/ContentType' + requestBody: + content: + application/json: + schema: + allOf: + - type: object + properties: + id: + type: integer + description: Unique ID of the *Bulk Pricing Rule*. Read-Only. + readOnly: true + required: + - id + - $ref: '#/components/schemas/bulkPricingRule_Full' + required: true + responses: + '200': + description: '' + content: + application/json: + schema: + type: object + properties: + data: + title: Bulk Pricing Rule + required: + - amount + - quantity_max + - quantity_min + - type + type: object + properties: + id: + type: integer + description: Unique ID of the *Bulk Pricing Rule*. Read-Only. + readOnly: true + quantity_min: + minimum: 0 + type: integer + description: | + The minimum inclusive quantity of a product to satisfy this rule. Must be greater than or equal to zero. + Required in /POST. + example: 10 + x-required: + - post + quantity_max: + minimum: 0 + type: integer + description: |- + The maximum inclusive quantity of a product to satisfy this rule. Must be greater than the `quantity_min` value – unless this field has a value of 0 (zero), in which case there will be no maximum bound for this rule. + Required in /POST. + example: 50 + x-required: + - post + type: + type: string + description: |- + The type of adjustment that is made. Values: `price` - the adjustment amount per product; `percent` - the adjustment as a percentage of the original price; `fixed` - the adjusted absolute price of the product. + Required in /POST. + example: price + enum: + - price + - percent + - fixed + x-required: + - post + amount: + type: integer + description: |- + The discount can be a fixed dollar amount or a percentage. For a fixed dollar amount enter it as an integer and the response will return as an integer. For percentage enter the amount as the percentage divided by 100 using string format. For example 10% percent would be “.10”. The response will return as an integer. + Required in /POST. + description: Common BulkPricingRule properties + meta: + $ref: '#/components/schemas/metaEmpty_Full' + example: + data: + id: 83 + quantity_min: 1 + quantity_max: 3 + type: price + amount: 1 + meta: {} + '404': + description: | + The resource or parent resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + '409': + description: | + The `BulkPricingRule` was in conflict with another bulk pricing rule. This is the result of quantity range overlapping with existing bulk pricing rules. + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + '422': + description: | + The `BulkPricingRule` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + x-codegen-request-body-name: BulkPricingRule + delete: + tags: + - Bulk Pricing Rules + summary: Delete a Bulk Pricing Rule + description: Deletes a *Bulk Pricing Rule*. + operationId: deleteBulkPricingRuleById + responses: + '204': + description: '' + content: {} + '404': + description: | + The resource or parent resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + parameters: + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/ProductIdParam' + - $ref: '#/components/parameters/BulkPricingRuleIdParam' + '/catalog/products/{product_id}/metafields': + get: + tags: + - Metafields + summary: Get All Product Metafields + description: Returns a list of *Product Metafields*. Optional parameters can be passed in. + operationId: getProductMetafieldsByProductId + parameters: + - name: page + in: query + description: Specifies the page number in a limited (paginated) list of products. + schema: + type: integer + - name: limit + in: query + description: Controls the number of items per page in a limited (paginated) list of products. + schema: + type: integer + - name: key + in: query + description: | + Filter based on a metafield's key. + schema: + type: string + - name: namespace + in: query + description: Filter based on a metafield's namespace. + schema: + type: string + - name: include_fields + in: query + description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' + schema: + type: string + - name: exclude_fields + in: query + description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + title: Meta Field Collection Response + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/metafield_Full' + meta: + $ref: '#/components/schemas/metaCollection_Full' + example: + data: + - id: 6 + key: Location + value: 4HG + namespace: Warehouse Locations + permission_set: app_only + resource_type: product + resource_id: 111 + description: Location in the warehouse + date_created: '1973-01-20T21:34:57.903Z' + date_modified: '1990-12-30T00:29:23.515Z' + - id: 7 + key: Sublocation + value: 4HG + namespace: Warehouse Locations + permission_set: read + resource_type: product + resource_id: 111 + description: Location in the warehouse + date_created: '1973-01-20T21:34:57.903Z' + date_modified: '1990-12-30T00:29:23.515Z' + meta: + pagination: + total: 2 + count: 2 + per_page: 50 + current_page: 1 + total_pages: 1 + links: + current: '?page=1&limit=50' + '404': + description: | + The resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + post: + tags: + - Metafields + summary: Create a Product Metafield + description: |- + Creates a *Product Metafield*. + + **Required Fields:** + * permission_set + * namespace + * key + * value + + **Note:** The maxiumum number of metafields allowed on each order, product, category, variant, or brand is 250 per client ID. For more information, see [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center. + operationId: createProductMetafield + parameters: + - $ref: '#/components/parameters/ContentType' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/metafield_Base' + required: true + responses: + '200': + description: '' + content: + application/json: + schema: + title: Metafield Response + type: object + properties: + data: + $ref: '#/components/schemas/metafield_Full' + meta: + $ref: '#/components/schemas/metaEmpty_Full' + example: + data: + id: 8 + key: location_id + value: 'Shelf 3, Bin 5' + namespace: Inventory Namespace + permission_set: read + resource_type: product + resource_id: 158 + description: Where products are located + date_created: '2018-09-13T16:42:37+00:00' + date_modified: '2018-09-13T16:42:37+00:00' + meta: {} + '409': + description: | + The `Metafield` was in conflict with another `Metafield`. This can be the result of duplicate unique key combinations of the app's client ID, namespace, key, resource_type, and resource_id. + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: |- + The HTTP status code. + title: + type: string + description: |- + The error title describing the particular error. + type: + type: string + '422': + description: | + The `Metafield` was not valid. This is the result of missing required fields, or of invalid data. See the response for more details. + content: + application/json: + schema: + title: Error Response + type: object + properties: + errors: + title: Detailed Errors + type: object + properties: {} + additionalProperties: true + instance: + type: string + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + parameters: + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/ProductIdParam' + '/catalog/products/{product_id}/metafields/{metafield_id}': + get: + tags: + - Metafields + summary: Get a Product Metafield + description: Returns a single *Product Metafield*. Optional parameters can be passed in. + operationId: getProductMetafieldByProductId + parameters: + - name: include_fields + in: query + description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' + schema: + type: string + - name: exclude_fields + in: query + description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + title: Metafield Response + type: object + properties: + data: + $ref: '#/components/schemas/metafield_Full' + meta: + $ref: '#/components/schemas/metaEmpty_Full' + example: + data: + id: 4 + key: location_id + value: 'Shelf 3, Bin 5' + namespace: App Namespace + permission_set: app_only + resource_type: product + resource_id: 137 + description: Where products are located + date_created: '2021-08-06T19:15:35+00:00' + date_modified: '2021-08-06T19:15:35+00:00' + meta: {} + '404': + description: | + The resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + put: + tags: + - Metafields + summary: Update a Product Metafield + description: "Updates a *Product Metafield*.\n\n**Required Fields**\n* none\n\n**Read-Only Fields**\n* id\n* These fields can only be modified using the API account that created the metafield:\n\t* `namespace`\n\t* `key`\n\t* `permission_set`\n\t* `value`\n\n**Usage Notes**\n* Attempting to modify the `namespace`, `key`, `permission_set`, or `value` field using an API account different from the one used to create those metafields will result in a `403` error message. " + operationId: updateProductMetafield + parameters: + - $ref: '#/components/parameters/ContentType' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/metafield_Base' + required: true + responses: + '200': + description: '' + content: + application/json: + schema: + title: Metafield Response + type: object + properties: + data: + $ref: '#/components/schemas/metafield_Full' + meta: + $ref: '#/components/schemas/metaEmpty_Full' + example: + data: + id: 4 + key: location_id + value: 'Shelf 3, Bin 5' + namespace: App Namespace + permission_set: app_only + resource_type: product + resource_id: 137 + description: Where products are located + date_created: '2021-08-06T19:15:35+00:00' + date_modified: '2021-08-06T19:15:35+00:00' + meta: {} + '404': + description: | + The resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + x-codegen-request-body-name: Metafield + delete: + tags: + - Metafields + summary: Delete a Product Metafield + description: Deletes a *Product Metafield*. + operationId: deleteProductMetafieldById + responses: + '204': + description: '' + content: {} + parameters: + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/ProductIdParam' + - $ref: '#/components/parameters/MetafieldIdParam' + '/catalog/products/{product_id}/reviews': + get: + tags: + - Reviews + summary: Get Product Reviews + description: Returns a list of all *Product Reviews*. Optional parameters can be passed in. + operationId: getProductReviews + parameters: + - name: include_fields + in: query + description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' + schema: + type: string + - name: exclude_fields + in: query + description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' + schema: + type: string + - name: page + in: query + description: Specifies the page number in a limited (paginated) list of products. + schema: + type: integer + - name: limit + in: query + description: Controls the number of items per page in a limited (paginated) list of products. + schema: + type: integer + - name: status + in: query + description: 'Filter items by status. `1` for approved, `0` for pending.' + schema: + type: integer + responses: + '200': + description: '' + content: + application/json: + schema: + title: Product Review Collection Response + type: object + properties: + data: + type: array + items: + title: Product Review + type: object + description: | + A product review model. + allOf: + - title: Product Review Base + required: + - date_reviewed + - title + type: object + properties: + title: + maxLength: 255 + minLength: 0 + type: string + description: |- + The title for the product review. + Required in /POST. + text: + type: string + description: | + The text for the product review. + status: + type: string + description: | + The status of the product review. Must be one of `approved`, `disapproved` or `pending`. + rating: + type: integer + description: 'The rating of the product review. Must be one of 0, 1, 2, 3, 4, 5.' + email: + type: string + description: 'The email of the reviewer. Must be a valid email, or an empty string.' + name: + maxLength: 255 + minLength: 0 + type: string + description: The name of the reviewer. + date_reviewed: + type: string + description: | + Date the product was reviewed. Required in /POST. + format: date-time + - type: object + properties: + id: + type: integer + description: | + The unique numeric ID of the product review; increments sequentially. + product_id: + type: integer + description: | + The unique numeric identifier for the product with which the review is associated. + date_created: + type: string + description: | + Date the product review was created. + format: date-time + date_modified: + type: string + description: | + Date the product review was modified. + format: date-time + meta: + $ref: '#/components/schemas/metaCollection_Full' + '204': + description: | + There are no reviews on this product. + content: {} + '404': + description: | + The product ID does not exist. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + post: + tags: + - Reviews + summary: Create a Product Review + description: |- + Creates a *Product Review*. + + **Required Fields** + - title + - date_reviewed + + **Read-Only Fields** + * id + operationId: createProductReview + parameters: + - $ref: '#/components/parameters/ContentType' + requestBody: + content: + application/json: + schema: + title: Product Review Post + description: | + The model for a POST to create a product review. + allOf: + - title: Product Review Base + required: + - date_reviewed + - title + type: object + properties: + title: + maxLength: 255 + minLength: 0 + type: string + description: |- + The title for the product review. + Required in /POST. + text: + type: string + description: | + The text for the product review. + status: + type: string + description: | + The status of the product review. Must be one of `approved`, `disapproved` or `pending`. + rating: + type: integer + description: 'The rating of the product review. Must be one of 0, 1, 2, 3, 4, 5.' + email: + type: string + description: 'The email of the reviewer. Must be a valid email, or an empty string.' + name: + maxLength: 255 + minLength: 0 + type: string + description: The name of the reviewer. + date_reviewed: + type: string + description: | + Date the product was reviewed. Required in /POST. + format: date-time + required: true + responses: + '200': + description: '' + content: + application/json: + schema: + title: Product Review Response + type: object + properties: + data: + title: Product Review + type: object + description: | + A product review model. + allOf: + - title: Product Review Base + required: + - date_reviewed + - title + type: object + properties: + title: + maxLength: 255 + minLength: 0 + type: string + description: |- + The title for the product review. + Required in /POST. + text: + type: string + description: | + The text for the product review. + status: + type: string + description: | + The status of the product review. Must be one of `approved`, `disapproved` or `pending`. + rating: + type: integer + description: 'The rating of the product review. Must be one of 0, 1, 2, 3, 4, 5.' + email: + type: string + description: 'The email of the reviewer. Must be a valid email, or an empty string.' + name: + maxLength: 255 + minLength: 0 + type: string + description: The name of the reviewer. + date_reviewed: + type: string + description: | + Date the product was reviewed. Required in /POST. + format: date-time + - type: object + properties: + id: + type: integer + description: | + The unique numeric ID of the product review; increments sequentially. + product_id: + type: integer + description: | + The unique numeric identifier for the product with which the review is associated. + date_created: + type: string + description: | + Date the product review was created. + format: date-time + date_modified: + type: string + description: | + Date the product review was modified. + format: date-time + meta: + $ref: '#/components/schemas/metaEmpty_Full' + description: | + Response payload for the BigCommerce API. + example: + data: + title: irur + text: anim aute + status: Lorem ad sed voluptate + rating: 3 + email: esse Lorem laborum aute + name: 'ut in ' + date_reviewed: '2011-12-31T13:40:42.971Z' + id: 82495037 + product_id: 22609026 + date_created: '1985-01-17T07:37:20.439Z' + date_modified: '2004-09-28T14:38:21.973Z' + meta: {} + '404': + description: | + The product ID does not exist. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + x-codegen-request-body-name: productReview + parameters: + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/ProductIdParam' + '/catalog/products/{product_id}/reviews/{review_id}': + get: + tags: + - Reviews + summary: Get a Product Review + description: Returns a single *Product Review*. Optional parameters maybe passed in. + operationId: getProductReviewById + parameters: + - name: include_fields + in: query + description: 'Fields to include, in a comma-separated list. The ID and the specified fields will be returned.' + schema: + type: string + - name: exclude_fields + in: query + description: 'Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.' + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + title: Product Review Response + type: object + properties: + data: + title: Product Review + type: object + description: | + A product review model. + allOf: + - title: Product Review Base + required: + - date_reviewed + - title + type: object + properties: + title: + maxLength: 255 + minLength: 0 + type: string + description: |- + The title for the product review. + Required in /POST. + text: + type: string + description: | + The text for the product review. + status: + type: string + description: | + The status of the product review. Must be one of `approved`, `disapproved` or `pending`. + rating: + type: integer + description: 'The rating of the product review. Must be one of 0, 1, 2, 3, 4, 5.' + email: + type: string + description: 'The email of the reviewer. Must be a valid email, or an empty string.' + name: + maxLength: 255 + minLength: 0 + type: string + description: The name of the reviewer. + date_reviewed: + type: string + description: | + Date the product was reviewed. Required in /POST. + format: date-time + - type: object + properties: + id: + type: integer + description: | + The unique numeric ID of the product review; increments sequentially. + date_created: + type: string + description: | + Date the product review was created. + format: date-time + date_modified: + type: string + description: | + Date the product review was modified. + format: date-time + meta: + $ref: '#/components/schemas/metaEmpty_Full' + description: | + Response payload for the BigCommerce API. + example: + data: + title: irur + text: anim aute + status: Lorem ad sed voluptate + rating: 3 + email: esse Lorem laborum aute + name: 'ut in ' + date_reviewed: '2011-12-31T13:40:42.971Z' + id: 82495037 + product_id: 22609026 + date_created: '1985-01-17T07:37:20.439Z' + date_modified: '2004-09-28T14:38:21.973Z' + meta: {} + '404': + description: | + The resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + put: + tags: + - Reviews + summary: Update a Product Review + description: |- + Updates a *Product Review*. + + **Required Fields** + * none + + **Read-Only Fields** + * id + operationId: updateProductReview + parameters: + - $ref: '#/components/parameters/ContentType' + requestBody: + description: | + A BigCommerce `ProductReview` object. + content: + application/json: + schema: + title: Product Review Put + description: | + The model for a PUT to update a product review. + allOf: + - title: Product Review Base + required: + - date_reviewed + - title + type: object + properties: + title: + maxLength: 255 + minLength: 0 + type: string + description: |- + The title for the product review. + Required in /POST. + text: + type: string + description: | + The text for the product review. + status: + type: string + description: | + The status of the product review. Must be one of `approved`, `disapproved` or `pending`. + rating: + type: integer + description: 'The rating of the product review. Must be one of 0, 1, 2, 3, 4, 5.' + email: + type: string + description: 'The email of the reviewer. Must be a valid email, or an empty string.' + name: + maxLength: 255 + minLength: 0 + type: string + description: The name of the reviewer. + date_reviewed: + type: string + description: | + Date the product was reviewed. Required in /POST. + format: date-time + required: true + responses: + '200': + description: '' + content: + application/json: + schema: + title: Product Review Response + type: object + properties: + data: + title: Product Review + type: object + description: | + A product review model. + allOf: + - title: Product Review Base + required: + - date_reviewed + - title + type: object + properties: + title: + maxLength: 255 + minLength: 0 + type: string + description: |- + The title for the product review. + Required in /POST. + text: + type: string + description: | + The text for the product review. + status: + type: string + description: | + The status of the product review. Must be one of `approved`, `disapproved` or `pending`. + rating: + type: integer + description: 'The rating of the product review. Must be one of 0, 1, 2, 3, 4, 5.' + email: + type: string + description: 'The email of the reviewer. Must be a valid email, or an empty string.' + name: + maxLength: 255 + minLength: 0 + type: string + description: The name of the reviewer. + date_reviewed: + type: string + description: | + Date the product was reviewed. Required in /POST. + format: date-time + - type: object + properties: + id: + type: integer + description: | + The unique numeric ID of the product review; increments sequentially. + product_id: + type: integer + description: | + The unique numeric identifier for the product with which the review is associated. + date_created: + type: string + description: | + Date the product review was created. + format: date-time + date_modified: + type: string + description: | + Date the product review was modified. + format: date-time + meta: + $ref: '#/components/schemas/metaEmpty_Full' + description: | + Response payload for the BigCommerce API. + example: + data: + title: irur + text: anim aute + status: Lorem ad sed voluptate + rating: 3 + email: esse Lorem laborum aute + name: 'ut in ' + date_reviewed: '2011-12-31T13:40:42.971Z' + id: 82495037 + product_id: 22609026 + date_created: '1985-01-17T07:37:20.439Z' + date_modified: '2004-09-28T14:38:21.973Z' + meta: {} + '404': + description: | + The resource was not found. + content: + application/json: + schema: + title: Not Found + type: object + properties: + status: + type: integer + description: | + 404 HTTP status code. + title: + type: string + description: The error title describing the particular error. + type: + type: string + instance: + type: string + description: Error payload for the BigCommerce API. + x-codegen-request-body-name: productReview + delete: + tags: + - Reviews + summary: Delete a Product Review + description: Deletes a *Product Review*. + operationId: deleteProductReview + responses: + '204': + description: '' + content: {} + parameters: + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/ProductIdParam' + - $ref: '#/components/parameters/ReviewIdParam' + '/catalog/products/channel-assignments': + get: + summary: Get Products Channel Assignments + description: Returns a list of products channel assignments. + operationId: GetProductsChannelAssignments + tags: + - Channel Assignments + parameters: + - name: page + in: query + schema: + type: integer + - name: limit + in: query + schema: + type: integer + - name: 'product_id:in' + in: query + schema: + type: string + - name: 'channel_id:in' + in: query + schema: + type: string + responses: + '200': + description: Collection of channel assignments. + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/ProductChannelAssignment' + meta: + $ref: '#/components/schemas/MetaPaginationObject' + put: + summary: Create Products Channel Assignments + description: Creates products channel assignments. + operationId: CreateProductsChannelAssignments + parameters: + - $ref: '#/components/parameters/ContentType' + tags: + - Channel Assignments + requestBody: + required: true + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/ProductChannelAssignment' + responses: + '204': + description: Updated + '422': + description: Error response for batch PUT of Channel Assignments. Includes the errors for each reference id. + content: + application/json: + schema: + $ref: '#/components/schemas/beta5ErrorResponse' + delete: + summary: Delete Products Channel Assignments + description: Delete products channel assignments. A filter must be supplied. + operationId: DeleteProductsChannelAssignments + tags: + - Channel Assignments + parameters: + - name: 'product_id:in' + in: query + schema: + type: string + - name: 'channel_id:in' + in: query + schema: + type: string + responses: + '204': + description: Deleted + '422': + description: At least one filter must be provided in order to delete channel assignments + content: + application/json: + schema: + $ref: '#/components/schemas/beta5ErrorResponse' + parameters: + - $ref: '#/components/parameters/Accept' + '/catalog/products/category-assignments': + get: + summary: Get Products Category Assignments + description: Returns a list of products category assignments. + operationId: GetProductsCategoryAssignments + tags: + - Category Assignments + parameters: + - name: page + in: query + schema: + type: integer + - name: limit + in: query + schema: + type: integer + - name: 'product_id:in' + in: query + schema: + type: string + - name: 'category_id:in' + in: query + schema: + type: string + responses: + '200': + description: Collection of category assignments. + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/ProductCategoryAssignment' + meta: + $ref: '#/components/schemas/MetaPaginationObject' + put: + summary: Create Products Category Assignments. + description: Creates products category assignments. + operationId: CreateProductsCategoryAssignments + parameters: + - $ref: '#/components/parameters/ContentType' + tags: + - Category Assignments + requestBody: + required: true + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/ProductCategoryAssignment' + responses: + '204': + description: Updated + '422': + description: Error response for batch PUT of Category Assignments. Includes the errors for each reference id. + content: + application/json: + schema: + $ref: '#/components/schemas/beta5ErrorResponse' + delete: + summary: Delete Products Category Assignments + description: Deletes products category assignments. A filter must be supplied. + operationId: DeleteProductsCategoryAssignments + tags: + - Category Assignments + parameters: + - name: 'product_id:in' + in: query + schema: + type: string + - name: 'category_id:in' + in: query + schema: + type: string + responses: + '204': + description: Deleted + '422': + description: At least one filter must be provided in order to delete category assignments + content: + application/json: + schema: + $ref: '#/components/schemas/beta5ErrorResponse' + parameters: + - $ref: '#/components/parameters/Accept' + '/catalog/summary': + get: + tags: + - Summary + summary: Get a Catalog Summary + description: |- + Returns a lightweight inventory summary from the BigCommerce Catalog. + + The inventory summary includes: + * "inventory_count" + * "variant_count" + * "inventory_value" + * "highest_variant_price" + * "average_variant_price" + * "lowest_variant_price" + * "oldest_variant_date" + * "newest_variant_date" + * "primary_category_id" + * "primary_category_name" + operationId: getCatalogSummary + responses: + '200': + description: '' + content: + application/json: + schema: + title: Catalog Summary Response + type: object + properties: + data: + title: Catalog Summary + type: object + properties: + inventory_count: + type: integer + description: | + A count of all inventory items in the catalog. + example: 2000 + inventory_value: + type: number + description: | + Total value of store's inventory. + format: double + example: 267000 + primary_category_id: + type: integer + description: | + ID of the category containing the most products. + example: 23 + primary_category_name: + type: string + description: | + Name of the category containing the most products. + example: Shop All + variant_count: + type: integer + description: Total number of variants + example: 46 + highest_variant_price: + type: number + description: Highest priced variant + format: double + example: 249 + average_variant_price: + type: number + description: Average price of all variants + format: double + example: 83.07978261 + lowest_variant_price: + type: string + description: Lowest priced variant in the store + example: '7' + oldest_variant_date: + type: string + example: '2018-08-15T00:00:00+00:00' + newest_variant_date: + type: string + example: '2018-08-16T00:00:00+00:00' + description: Catalog Summary object describes a lightweight summary of the catalog. + meta: + $ref: '#/components/schemas/metaEmpty_Full' + parameters: + - $ref: '#/components/parameters/Accept' +components: + schemas: + productModifier_Base: + title: productModifier_Base + required: + - required + - type + type: object + properties: + type: + type: string + description: | + BigCommerce API, which determines how it will display on the storefront. Acceptable values: `date`, `checkbox`, `file`, `text`, `multi_line_text`, `numbers_only_text`, `radio_buttons`, `rectangles`, `dropdown`, `product_list`, `product_list_with_images`, `swatch`. Required in a /POST. + enum: + - date + - checkbox + - file + - text + - multi_line_text + - numbers_only_text + - radio_buttons + - rectangles + - dropdown + - product_list + - product_list_with_images + - swatch + x-required: + - post + required: + type: boolean + description: | + Whether or not this modifer is required or not at checkout. Required in a /POST. + x-required: + - post + sort_order: + type: integer + description: The order the modifiers display on the product detail page. + config: + $ref: '#/components/schemas/config_Full' + display_name: + type: string + description: The name of the option shown on the storefront. + description: Common Modifier properties. + x-internal: false + productModifier_Full: + title: productModifier_Full + description: Product Modifier + allOf: + - $ref: '#/components/schemas/productModifier_Base' + - type: object + properties: + id: + type: integer + description: | + The unique numeric ID of the modifier; increments sequentially. + example: 12 + product_id: + type: integer + description: | + The unique numeric ID of the product to which the option belongs. + example: 77 + name: + type: string + description: | + The unique option name. Auto-generated from the display name, a timestamp, and the product ID. + example: Add-a-$5-Donation1535039590-191 + option_values: + type: array + items: + $ref: '#/components/schemas/productModifierOptionValue_Full' + x-internal: false + productModifierOptionValue_Base: + title: productModifierOptionValue_Base + required: + - label + - sort_order + type: object + properties: + is_default: + type: boolean + description: | + The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. + example: false + label: + type: string + description: | + The text display identifying the value on the storefront. Required in a /POST. + example: Green + x-required: + - post + sort_order: + maximum: 2147483647 + minimum: -2147483648 + type: integer + description: | + The order in which the value will be displayed on the product page. Required in a /POST. + example: 0 + x-required: + - post + value_data: + type: object + properties: {} + description: | + Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. If no data is available, returns `null`. + nullable: true + adjusters: + $ref: '#/components/schemas/adjusters_Full' + description: Common Product Modifer `option_value` properties. + x-internal: false + productModifierOptionValue_Full: + title: productModifierOptionValue_Full + description: Product Modifer `option_value`. + allOf: + - $ref: '#/components/schemas/productModifierOptionValue_Base' + - type: object + properties: + id: + type: integer + description: | + The unique numeric ID of the value; increments sequentially. + option_id: + type: integer + x-internal: false + productOption_Base: + title: productOption_Base + type: object + properties: + id: + type: integer + description: | + The unique numerical ID of the option, increments sequentially. + nullable: true + example: 55 + product_id: + type: integer + description: | + The unique numerical ID of the product to which the option belongs. + example: 4 + x-required: + - post + - put + display_name: + maxLength: 255 + minLength: 1 + type: string + description: | + The name of the option shown on the storefront. + example: Add-a-$5-Donation1535042499-187 + x-required: + - post + - put + type: + type: string + description: | + The type of option, which determines how it will display on the storefront. Acceptable values: `radio_buttons`, `rectangles`, `dropdown`, `product_list`, `product_list_with_images`, `swatch`. For reference, the former v2 API values are: RB = radio_buttons, RT = rectangles, S = dropdown, P = product_list, PI = product_list_with_images, CS = swatch. + enum: + - radio_buttons + - rectangles + - dropdown + - product_list + - product_list_with_images + - swatch + x-required: + - post + - put + config: + $ref: '#/components/schemas/productOptionConfig_Full' + sort_order: + type: integer + description: 'Order in which the option is displayed on the storefront. ' + example: 1 + option_values: + type: array + items: + $ref: '#/components/schemas/productOptionOptionValue_Full' + description: Common Option properties. + x-internal: false + productVariant_Base: + title: productVariant_Base + type: object + properties: + cost_price: + minimum: 0 + type: number + description: The cost price of the variant. Not affected by Price List prices. + format: double + nullable: true + price: + minimum: 0 + type: number + description: 'This variant’s base price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is `null`, the product’s default price (set in the Product resource’s `price` field) will be used as the base price.' + format: double + nullable: true + sale_price: + minimum: 0 + type: number + description: 'This variant’s sale price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s sale price (set in the Product resource’s `price` field) will be used as the sale price.' + format: double + nullable: true + retail_price: + minimum: 0 + type: number + description: 'This variant’s retail price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s retail price (set in the Product resource’s `price` field) will be used as the retail price.' + format: double + nullable: true + weight: + minimum: 0 + type: number + description: 'This variant’s base weight on the storefront. If this value is null, the product’s default weight (set in the Product resource’s weight field) will be used as the base weight.' + format: double + nullable: true + width: + minimum: 0 + type: number + description: | + Width of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default width (set in the Product resource's `width` field) will be used as the base width. + format: double + nullable: true + height: + minimum: 0 + type: number + description: | + Height of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default height (set in the Product resource's `height` field) will be used as the base height. + format: double + nullable: true + depth: + minimum: 0 + type: number + description: | + Depth of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default depth (set in the Product resource's `depth` field) will be used as the base depth. + format: double + nullable: true + is_free_shipping: + type: boolean + description: | + Flag used to indicate whether the variant has free shipping. If `true`, the shipping cost for the variant will be zero. + fixed_cost_shipping_price: + minimum: 0 + type: number + description: | + A fixed shipping cost for the variant. If defined, this value will be used during checkout instead of normal shipping-cost calculation. + format: double + nullable: true + purchasing_disabled: + type: boolean + description: 'If `true`, this variant will not be purchasable on the storefront.' + purchasing_disabled_message: + maxLength: 255 + minLength: 0 + type: string + description: 'If `purchasing_disabled` is `true`, this message should show on the storefront when the variant is selected.' + upc: + type: string + description: The UPC code used in feeds for shopping comparison sites and external channel integrations. + nullable: true + inventory_level: + type: integer + description: |- + Inventory level for the variant, which is used when the product’s inventory_tracking is set to `variant`. The Catalog API returns the inventory for only the default location. + + The inventory for a variant cannot exceed 2,147,483,647 in the catalog. The sum of the variant inventories, or the total inventory for a product, cannot exceed 2,147,483,647. + + If you exceed the limit, the store sets the variant inventory to the limit if no other variant inventories are set. If other variant inventories are set, the store does not save the variant inventory rather than setting the variant inventory to the remaining limit. + + The Catalog API handles limits in a different way than the Inventory API. For more information, see [Limit handling](/docs/store-operations/catalog/inventory-adjustments#limit-handling-in-inventory-versus-catalog-api). + nullable: true + maximum: 2147483647 + inventory_warning_level: + type: integer + description: 'When the variant hits this inventory level, it is considered low stock.' + nullable: true + maximum: 2147483647 + bin_picking_number: + maxLength: 255 + minLength: 0 + type: string + description: Identifies where in a warehouse the variant is located. + nullable: true + mpn: + type: string + description: The Manufacturer Part Number (MPN) for the variant. + gtin: + type: string + example: '012345678905' + description: Common Variant properties. + x-internal: false + x-examples: + example-1: + cost_price: 0 + price: 0 + sale_price: 0 + retail_price: 0 + weight: 0 + width: 0 + height: 0 + depth: 0 + is_free_shipping: true + fixed_cost_shipping_price: 0 + purchasing_disabled: true + purchasing_disabled_message: string + upc: string + inventory_level: 0 + inventory_warning_level: 0 + bin_picking_number: string + mpn: string + gtin: '012345678905' + productVariant_Full: + title: productVariant_Full + allOf: + - $ref: '#/components/schemas/productVariant_Base' + - type: object + properties: + product_id: + type: integer + sku: + type: string + option_values: + type: array + description: Array of option and option values IDs that make up this variant. Will be empty if the variant is the product's base variant. + items: + $ref: '#/components/schemas/productVariantOptionValue_Full' + calculated_price: + type: number + description: | + The price of the variant as seen on the storefront. This price takes into account `sale_price` and any price adjustment rules that are applicable to this variant. + format: double + calculated_weight: + type: number + required: + - sku + x-internal: false + description: '' + x-examples: + example-1: + cost_price: 0 + price: 0 + sale_price: 0 + retail_price: 0 + weight: 0 + width: 0 + height: 0 + depth: 0 + is_free_shipping: true + fixed_cost_shipping_price: 0 + purchasing_disabled: true + purchasing_disabled_message: string + upc: string + inventory_level: 0 + inventory_warning_level: 0 + bin_picking_number: string + mpn: string + gtin: '012345678905' + id: 0 + product_id: 0 + sku: string + sku_id: 0 + option_values: + - option_display_name: Color + label: Beige + id: 146 + option_id: 151 + calculated_price: 0 + calculated_weight: 0 + productVariant_Put_Product: + title: productVariant_Put_Product + type: object + properties: + cost_price: + minimum: 0 + type: number + description: The cost price of the variant. Not affected by Price List prices. + format: double + nullable: true + price: + minimum: 0 + type: number + description: 'This variant’s base price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is `null`, the product’s default price (set in the Product resource’s `price` field) will be used as the base price.' + format: double + nullable: true + sale_price: + minimum: 0 + type: number + description: 'This variant’s sale price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s sale price (set in the Product resource’s `price` field) will be used as the sale price.' + format: double + nullable: true + retail_price: + minimum: 0 + type: number + description: 'This variant’s retail price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s retail price (set in the Product resource’s `price` field) will be used as the retail price.' + format: double + nullable: true + weight: + minimum: 0 + type: number + description: 'This variant’s base weight on the storefront. If this value is null, the product’s default weight (set in the Product resource’s weight field) will be used as the base weight.' + format: double + nullable: true + width: + minimum: 0 + type: number + description: | + Width of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default width (set in the Product resource's `width` field) will be used as the base width. + format: double + nullable: true + height: + minimum: 0 + type: number + description: | + Height of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default height (set in the Product resource's `height` field) will be used as the base height. + format: double + nullable: true + depth: + minimum: 0 + type: number + description: | + Depth of the variant, which can be used when calculating shipping costs. If this value is `null`, the product's default depth (set in the Product resource's `depth` field) will be used as the base depth. + format: double + nullable: true + is_free_shipping: + type: boolean + description: | + Flag used to indicate whether the variant has free shipping. If `true`, the shipping cost for the variant will be zero. + fixed_cost_shipping_price: + minimum: 0 + type: number + description: | + A fixed shipping cost for the variant. If defined, this value will be used during checkout instead of normal shipping-cost calculation. + format: double + nullable: true + purchasing_disabled: + type: boolean + description: 'If `true`, this variant will not be purchasable on the storefront.' + purchasing_disabled_message: + maxLength: 255 + minLength: 0 + type: string + description: 'If `purchasing_disabled` is `true`, this message should show on the storefront when the variant is selected.' + upc: + type: string + description: The UPC code used in feeds for shopping comparison sites and external channel integrations. + nullable: true + inventory_level: + type: integer + description: |- + Inventory level for the variant, which is used when the product’s inventory_tracking is set to `variant`. The Catalog API returns the inventory for only the default location. + + The inventory for a variant cannot exceed 2,147,483,647 in the catalog. The sum of the variant inventories, or the total inventory for a product, cannot exceed 2,147,483,647. + + If you exceed the limit, the store sets the variant inventory to the limit if no other variant inventories are set. If other variant inventories are set, the store does not save the variant inventory rather than setting the variant inventory to the remaining limit. + + The Catalog API handles limits in a different way than the Inventory API. For more information, see [Limit handling](/docs/store-operations/catalog/inventory-adjustments#limit-handling-in-inventory-versus-catalog-api). + nullable: true + maximum: 2147483647 + inventory_warning_level: + type: integer + description: 'When the variant hits this inventory level, it is considered low stock.' + nullable: true + maximum: 2147483647 + bin_picking_number: + maxLength: 255 + minLength: 0 + type: string + description: Identifies where in a warehouse the variant is located. + nullable: true + product_id: + type: integer + description: Product ID + id: + type: integer + description: Variant ID + sku: + maxLength: 255 + minLength: 1 + type: string + description: | + The model for a PUT to update variants on a product. + required: + - product_id + - id + x-internal: false + productVariantOptionValue_Full: + title: productVariantOptionValue_Full + allOf: + - type: object + properties: + option_display_name: + maxLength: 255 + minLength: 1 + type: string + description: | + The name of the option. + example: Color + x-required: + - post + label: + maxLength: 255 + minLength: 1 + type: string + description: | + The label of the option value. + example: Beige + x-required: + - post + required: + - option_display_name + - label + x-internal: false + productVariantOptionValue_Base: + title: productVariantOptionValue_Base + type: object + properties: + id: + type: integer + description: '`option_value` ID.' + example: 146 + option_id: + type: integer + description: '`option` ID.' + example: 151 + description: Common Product Variant Option properties. + x-internal: false + productOptionOptionValue_Base: + title: productOptionOptionValue_Base + required: + - label + - sort_order + type: object + properties: + is_default: + type: boolean + description: | + The flag for preselecting a value as the default on the storefront. This field is not supported for swatch options/modifiers. + example: false + label: + type: string + description: | + The text display identifying the value on the storefront. Required in a /POST. + example: Green + x-required: + - post + sort_order: + maximum: 2147483647 + minimum: -2147483648 + type: integer + description: | + The order in which the value will be displayed on the product page. Required in a /POST. + example: 0 + x-required: + - post + value_data: + type: object + properties: {} + description: | + Extra data describing the value, based on the type of option or modifier with which the value is associated. The `swatch` type option can accept an array of `colors`, with up to three hexidecimal color keys; or an `image_url`, which is a full image URL path including protocol. The `product list` type option requires a `product_id`. The `checkbox` type option requires a boolean flag, called `checked_value`, to determine which value is considered to be the checked state. If no data is available, returns `null`. + nullable: true + description: Common Product Option `option_value` properties. + x-internal: false + productOptionOptionValue_Full: + title: productOptionOptionValue_Full + description: Product Option `option_value`. + allOf: + - $ref: '#/components/schemas/productOptionOptionValue_Base' + - type: object + properties: + id: + type: integer + description: | + The unique numeric ID of the value; increments sequentially. + x-internal: false + productImage_Base: + title: productImage_Base + type: object + properties: + image_file: + type: string + description: | + The local path to the original image file uploaded to BigCommerce. Use image_url when creating a product. + + Must be sent as a `multipart/form-data` field in the request body. Limit of 8 MB per file. + is_thumbnail: + type: boolean + description: | + Flag for identifying whether the image is used as the product's thumbnail. + sort_order: + maximum: 2147483647 + minimum: -2147483648 + type: integer + description: | + The order in which the image will be displayed on the product page. Higher integers give the image a lower priority. When updating, if the image is given a lower priority, all images with a `sort_order` the same as or greater than the image's new `sort_order` value will have their `sort_order`s reordered. + description: + type: string + description: | + The description for the image. + image_url: + type: string + description: 'Must be a fully qualified URL path, including protocol. Limit of 8MB per file.' + description: Common ProductImage properties. + x-internal: false + productImage_Put: + title: productImage_Put + description: The model for a PUT to update applicable Product Image fields. + allOf: + - title: Product Image Base + type: object + properties: + product_id: + type: integer + description: | + The unique numeric identifier for the product with which the image is associated. + url_zoom: + readOnly: true + type: string + description: | + The zoom URL for this image. By default, this is used as the zoom image on product pages when zoom images are enabled. + url_standard: + readOnly: true + type: string + description: | + The standard URL for this image. By default, this is used for product-page images. + url_thumbnail: + readOnly: true + type: string + description: | + The thumbnail URL for this image. By default, this is the image size used on the category page and in side panels. + url_tiny: + readOnly: true + type: string + description: | + The tiny URL for this image. By default, this is the image size used for thumbnails beneath the product image on a product page. + description: Common ProductImage properties. + - $ref: '#/components/schemas/productImage_Base' + x-internal: false + productVideo_Base: + title: productVideo_Base + type: object + description: | + The model for a POST to create a video on a product. + x-internal: false + properties: + title: + type: string + maxLength: 255 + minLength: 0 + description: | + The title for the video. If left blank, this will be filled in according to data on a host site. + example: Writing Great Documentation + description: + type: string + description: | + The description for the video. If left blank, this will be filled in according to data on a host site. + example: A video about documenation + sort_order: + type: integer + maximum: 2147483647 + minimum: -2147483648 + description: | + The order in which the video will be displayed on the product page. Higher integers give the video a lower priority. When updating, if the video is given a lower priority, all videos with a `sort_order` the same as or greater than the video's new `sort_order` value will have their `sort_order`s reordered. + example: 1 + type: + type: string + description: | + The video type (a short name of a host site). + enum: + - youtube + video_id: + type: string + description: The ID of the video on a host site. + example: z3fRu9pkuXE + productVideo_Full: + title: productVideo_Full + description: | + A product video model. + allOf: + - $ref: '#/components/schemas/productVideo_Base' + - type: object + properties: + id: + type: integer + description: | + The unique numeric ID of the product video; increments sequentially. + product_id: + type: integer + description: | + The unique numeric identifier for the product with which the image is associated. + length: + type: string + description: | + Length of the video. This will be filled in according to data on a host site. + x-internal: false + product_Put: + title: product_Put + description: The model for a PUT to update a product. + allOf: + - $ref: '#/components/schemas/product_Base' + - type: object + properties: + variants: + type: array + items: + $ref: '#/components/schemas/productVariant_Put_Product' + x-internal: false + metafield_Base: + title: metafield_Base + type: object + description: 'Metafield for products, categories, variants, and brands; the max number of metafields allowed on each is 50. For more information, see [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center.' + x-internal: false + properties: + key: + maxLength: 64 + minLength: 1 + type: string + description: | + The name of the field, for example: `location_id`, `color`. Required for POST. + example: Location + x-required: + - post + value: + maxLength: 65535 + minLength: 1 + type: string + description: | + The value of the field, for example: `1`, `blue`. Required for POST. + example: 4HG + x-required: + - post + namespace: + maxLength: 64 + minLength: 1 + type: string + description: | + Namespace for the metafield, for organizational purposes. This is set by the developer. Required for POST. + example: Warehouse Locations + x-required: + - post + permission_set: + type: string + description: |- + Determines the visibility and writeability of the field by other API consumers. + + |Value|Description + |-|-| + |`app_only`|Private to the app that owns the field| + |`read`|Visible to other API consumers| + |`write`|Open for reading and writing by other API consumers| + |`read_and_sf_access`|Visible to other API consumers, including on storefront| + |`write_and_sf_access`|Open for reading and writing by other API consumers, including on storefront| + enum: + - app_only + - read + - write + - read_and_sf_access + - write_and_sf_access + description: + maxLength: 255 + minLength: 0 + type: string + description: | + Description for the metafields. + example: Location in the warehouse + required: + - permission_set + - namespace + - key + - value + complexRule_Base: + title: complexRule_Base + type: object + properties: + id: + type: integer + description: |- + The unique numeric ID of the rule; increments sequentially. + Read-Only + example: 5 + product_id: + type: integer + description: | + The unique numeric ID of the product with which the rule is associated; increments sequentially. + nullable: true + example: 67 + x-required: + - post + - put + sort_order: + maximum: 2147483647 + minimum: -2147483648 + type: integer + description: | + The priority to give this rule when making adjustments to the product properties. + example: 0 + enabled: + type: boolean + description: | + Flag for determining whether the rule is to be used when adjusting a product's price, weight, image, or availabilty. + example: true + stop: + type: boolean + description: | + Flag for determining whether other rules should not be applied after this rule has been applied. + purchasing_disabled: + type: boolean + description: | + Flag for determining whether the rule should disable purchasing of a product when the conditions are applied. + purchasing_disabled_message: + maxLength: 255 + minLength: 0 + type: string + description: | + Message displayed on the storefront when a rule disables the purchasing of a product. + example: This product is not available at this time. + purchasing_hidden: + type: boolean + description: | + Flag for determining whether the rule should hide purchasing of a product when the conditions are applied. + image_url: + type: string + description: | + The URL for an image displayed on the storefront when the conditions are applied. Limit of 8MB per file. + example: 'https://cdn8.bigcommerce.com/s-123456/product_images/d/fakeimage.png' + price_adjuster: + $ref: '#/components/schemas/adjuster_Full' + weight_adjuster: + $ref: '#/components/schemas/adjuster_Full' + conditions: + type: array + items: + $ref: '#/components/schemas/complexRuleConditionBase' + description: Common ComplexRule properties. + x-internal: false + productCustomField_Base: + title: productCustomField_Base + required: + - name + - value + type: object + properties: + id: + minimum: 1 + type: integer + description: |- + The unique numeric ID of the custom field; increments sequentially. + Read-Only + example: 6 + name: + maxLength: 250 + minLength: 1 + type: string + description: | + The name of the field, shown on the storefront, orders, etc. Required for /POST + example: ISBN + x-required: + - post + value: + maxLength: 250 + minLength: 1 + type: string + description: | + The name of the field, shown on the storefront, orders, etc. Required for /POST + example: '1234567890123' + x-required: + - post + description: 'Gets custom fields associated with a product. These allow you to specify additional information that will appear on the product’s page, such as a book’s ISBN or a DVD’s release date.' + x-internal: false + productCustomField_Put: + title: productCustomField_Put + required: + - name + - value + type: object + properties: + id: + minimum: 1 + type: integer + description: |- + The unique numeric ID of the custom field; increments sequentially. Required to update existing custom field in /PUT request. + Read-Only + example: 6 + name: + maxLength: 250 + minLength: 1 + type: string + description: | + The name of the field, shown on the storefront, orders, etc. Required for /POST + example: ISBN + x-required: + - post + value: + maxLength: 250 + minLength: 1 + type: string + description: | + The name of the field, shown on the storefront, orders, etc. Required for /POST + example: '1234567890123' + x-required: + - post + description: The model for a PUT to update a custom field on a product. + x-internal: false + complexRuleConditionBase: + title: complexRuleConditionBase + required: + - modifier_id + - modifier_value_id + - variant_id + type: object + properties: + id: + type: integer + description: | + The unique numeric ID of the rule condition; increments sequentially. Read-Only + nullable: true + example: 3 + rule_id: + type: integer + description: |- + The unique numeric ID of the rule with which the condition is associated. + Read-Only + nullable: true + example: 4 + modifier_id: + type: integer + description: |- + The unique numeric ID of the modifier with which the rule condition is associated. + Required in /POST. + nullable: true + example: 55 + modifier_value_id: + type: integer + description: |- + The unique numeric ID of the modifier value with which the rule condition is associated. + Required in /POST. + nullable: true + example: 256 + variant_id: + type: integer + description: |- + The unique numeric ID of the variant with which the rule condition is associated. + Required in /POST. + nullable: true + example: 1 + combination_id: + type: integer + description: | + (READ-ONLY:) The unique numeric ID of the SKU (v2 API), or Combination, with which the rule condition is associated. This is to maintain cross-compatibility between v2 and v3. + description: 'Complex rules may return with conditions that apply to one or more variants, or with a single modifier value (if the rules were created using the v2 API or the control panel). Complex rules created or updated in the v3 API must have conditions that either reference multiple `modifier_value_id`’s, or else reference a `modifier_value_id` and a `variant_id`.' + x-internal: false + customUrl_Full: + title: customUrl_Full + type: object + properties: + url: + maxLength: 255 + minLength: 0 + type: string + description: | + Product URL on the storefront. + x-required: + - post + - put + x-url: true + is_customized: + type: boolean + description: | + Returns `true` if the URL has been changed from its default state (the auto-assigned URL that BigCommerce provides). + x-required: + - post + - put + description: The custom URL for the product on the storefront. + x-internal: false + bulkPricingRule_Full: + title: bulkPricingRule_Full + type: object + description: Common Bulk Pricing Rule properties + x-internal: false + properties: + quantity_min: + minimum: 0 + type: integer + description: | + The minimum inclusive quantity of a product to satisfy this rule. Must be greater than or equal to zero. For `fixed` rules, the minimum quantity canʼt be less than two. + Required in /POST. + example: 10 + x-required: + - post + quantity_max: + minimum: 0 + type: integer + description: |- + The maximum inclusive quantity of a product to satisfy this rule. Must be greater than the `quantity_min` value – unless this field has a value of 0 (zero), in which case there will be no maximum bound for this rule. + Required in /POST. + example: 50 + x-required: + - post + type: + type: string + description: |- + The type of adjustment that is made. Values: `price` - the adjustment amount per product; `percent` - the adjustment as a percentage of the original price; `fixed` - the adjusted absolute price of the product. + Required in /POST. + example: price + enum: + - price + - percent + - fixed + x-required: + - post + amount: + oneOf: + - type: number + example: 10 + - type: string + example: '.10' + description: |- + You can express the adjustment type as either a fixed dollar amount or a percentage. Send a number; the response will return a number for `price` and `fixed` adjustments. + Divide the adjustment percentage by 100 and send the result in string format. For example, represent 10% as “.10”. The response will return a float value for both `price` and `percentage` adjustments. + Required in /POST. + required: + - quantity_min + - quantity_max + - type + - amount + productOptionConfig_Full: + title: productOptionConfig_Full + type: object + properties: + default_value: + type: string + description: | + (date, text, multi_line_text, numbers_only_text) The default value. Shown on a date option as an ISO-8601–formatted string, or on a text option as a string. + checked_by_default: + type: boolean + description: | + (checkbox) Flag for setting the checkbox to be checked by default. + checkbox_label: + type: string + description: | + (checkbox) Label displayed for the checkbox option. + date_limited: + type: boolean + description: | + (date) Flag to limit the dates allowed to be entered on a date option. + date_limit_mode: + type: string + description: | + (date) The type of limit that is allowed to be entered on a date option. + example: range + enum: + - earliest + - range + - latest + date_earliest_value: + type: string + description: | + (date) The earliest date allowed to be entered on the date option, as an ISO-8601 formatted string. + format: date + date_latest_value: + type: string + description: | + (date) The latest date allowed to be entered on the date option, as an ISO-8601 formatted string. + format: date + file_types_mode: + type: string + description: | + (file) The kind of restriction on the file types that can be uploaded with a file upload option. Values: `specific` - restricts uploads to particular file types; `all` - allows all file types. + example: specific + enum: + - specific + - all + file_types_supported: + type: array + description: | + (file) The type of files allowed to be uploaded if the `file_type_option` is set to `specific`. Values: + `images` - Allows upload of image MIME types (`bmp`, `gif`, `jpg`, `jpeg`, `jpe`, `jif`, `jfif`, `jfi`, `png`, `wbmp`, `xbm`, `tiff`). `documents` - Allows upload of document MIME types (`txt`, `pdf`, `rtf`, `doc`, `docx`, `xls`, `xlsx`, `accdb`, `mdb`, `one`, `pps`, `ppsx`, `ppt`, `pptx`, `pub`, `odt`, `ods`, `odp`, `odg`, `odf`). + `other` - Allows file types defined in the `file_types_other` array. + items: + type: string + example: 'images, documents, other' + file_types_other: + type: array + description: | + (file) A list of other file types allowed with the file upload option. + items: + type: string + example: pdf + file_max_size: + type: integer + description: | + (file) The maximum size for a file that can be used with the file upload option. This will still be limited by the server. + example: 5 + text_characters_limited: + type: boolean + description: | + (text, multi_line_text) Flag to validate the length of a text or multi-line text input. + text_min_length: + type: integer + description: | + (text, multi_line_text) The minimum length allowed for a text or multi-line text option. + example: 1 + text_max_length: + type: integer + description: | + (text, multi_line_text) The maximum length allowed for a text or multi line text option. + example: 55 + text_lines_limited: + type: boolean + description: | + (multi_line_text) Flag to validate the maximum number of lines allowed on a multi-line text input. + example: true + text_max_lines: + type: integer + description: | + (multi_line_text) The maximum number of lines allowed on a multi-line text input. + example: 4 + number_limited: + type: boolean + description: | + (numbers_only_text) Flag to limit the value of a number option. + example: true + number_limit_mode: + type: string + description: | + (numbers_only_text) The type of limit on values entered for a number option. + example: lowest + enum: + - lowest + - highest + - range + number_lowest_value: + type: number + description: | + (numbers_only_text) The lowest allowed value for a number option if `number_limited` is true. + example: 100 + number_highest_value: + type: number + description: | + (numbers_only_text) The highest allowed value for a number option if `number_limited` is true. + number_integers_only: + type: boolean + description: | + (numbers_only_text) Flag to limit the input on a number option to whole numbers only. + example: false + product_list_adjusts_inventory: + type: boolean + description: | + (product_list, product_list_with_images) Flag for automatically adjusting inventory on a product included in the list. + product_list_adjusts_pricing: + type: boolean + description: | + (product_list, product_list_with_images) Flag to add the optional product's price to the main product's price. + product_list_shipping_calc: + type: string + description: | + (product_list, product_list_with_images) How to factor the optional product's weight and package dimensions into the shipping quote. Values: `none` - don't adjust; `weight` - use shipping weight only; `package` - use weight and dimensions. + example: weight + enum: + - none + - weight + - package + description: The values for option config can vary based on the Modifier created. + x-internal: false + adjuster_Full: + title: adjuster_Full + type: object + properties: + adjuster: + type: string + description: | + The type of adjuster for either the price or the weight of the variant, when the modifier value is selected on the storefront. + nullable: true + enum: + - relative + - percentage + adjuster_value: + type: number + description: | + The numeric amount by which the adjuster will change either the price or the weight of the variant, when the modifier value is selected on the storefront. + example: 5 + description: Adjuster for Complex Rules. + x-internal: false + metaCollection_Full: + title: metaCollection_Full + type: object + properties: + pagination: + $ref: '#/components/schemas/pagination_Full' + description: 'Data about the response, including pagination and collection totals.' + x-internal: false + pagination_Full: + title: pagination_Full + type: object + properties: + total: + type: integer + description: | + Total number of items in the result set. + example: 36 + count: + type: integer + description: | + Total number of items in the collection response. + example: 36 + per_page: + type: integer + description: | + The amount of items returned in the collection per page, controlled by the limit parameter. + example: 50 + current_page: + type: integer + description: | + The page you are currently on within the collection. + example: 1 + total_pages: + type: integer + description: | + The total number of pages in the collection. + example: 1 + links: + type: object + properties: + previous: + type: string + description: | + Link to the previous page returned in the response. + current: + type: string + description: | + Link to the current page returned in the response. + example: '?page=1&limit=50' + next: + type: string + description: | + Link to the next page returned in the response. + description: | + Pagination links for the previous and next parts of the whole collection. + description: 'Data about the response, including pagination and collection totals.' + x-internal: false + metaEmpty_Full: + type: object + title: Response meta + properties: {} + additionalProperties: true + description: Response metadata. + error_Base: + title: error_Base + type: object + properties: + status: + type: integer + description: | + The HTTP status code. + title: + type: string + description: | + The error title describing the particular error. + type: + type: string + instance: + type: string + description: | + Error payload for the BigCommerce API. + x-internal: false + errorMultiStatus: + title: errorMultiStatus + type: object + properties: + status: + type: integer + minLength: 3 + maxLength: 3 + description: 'The [HTTP status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) of the failure or partial success.' + title: + type: string + description: A summary of the failure or partial success. + type: + type: string + description: A BigCommerce-defined error signifier. + errors: + $ref: '#/components/schemas/DetailedErrors' + DetailedErrors: + title: DetailedErrors + description: Each key-value pair describes a failure or partial success case. + type: object + properties: {} + additionalProperties: true + x-internal: false + product_Full: + title: product_Full + allOf: + - type: object + properties: + id: + minimum: 1 + type: integer + description: ID of the product. Read-Only. + readOnly: true + - $ref: '#/components/schemas/product_Base' + - type: object + properties: + date_created: + type: string + description: | + The date on which the product was created. + format: date-time + example: '2018-08-15T14:49:05+00:00' + date_modified: + type: string + description: | + The date on which the product was modified. + format: date-time + example: '2018-08-24T14:41:00+00:00' + base_variant_id: + type: integer + description: The unique identifier of the base variant associated with a simple product. This value is `null` for complex products. + calculated_price: + type: number + description: 'The calculated_price is derived from the default price and sale price of the product. It is equal to the sale price if set or the default price if there is not a sale price present. Depending on your store settings and customer group, or channel-specific pricing, this value may or may not be equal to the price seen on the storefront.' + format: float + options: + type: array + items: + $ref: '#/components/schemas/productOption_Base' + modifiers: + type: array + items: + $ref: '#/components/schemas/productModifier_Full' + map_price: + type: number + description: Minimum Advertised Price. + option_set_id: + type: integer + description: Indicates that the product is in an Option Set (legacy V2 concept). + option_set_display: + type: string + description: Legacy template setting which controls if the option set shows up to the side of or below the product image and description. + variants: + type: array + items: + $ref: '#/components/schemas/productVariant_Full' + x-internal: false + productImage_Full: + title: productImage_Full + description: Common ProductImage properties. + allOf: + - $ref: '#/components/schemas/productImage_Base' + - title: productImage + type: object + properties: + id: + type: integer + description: | + The unique numeric ID of the image; increments sequentially. + product_id: + type: integer + description: | + The unique numeric identifier for the product with which the image is associated. + url_zoom: + readOnly: true + type: string + description: | + The zoom URL for this image. By default, this is used as the zoom image on product pages when zoom images are enabled. + url_standard: + readOnly: true + type: string + description: | + The standard URL for this image. By default, this is used for product-page images. + url_thumbnail: + readOnly: true + type: string + description: | + The thumbnail URL for this image. By default, this is the image size used on the category page and in side panels. + url_tiny: + readOnly: true + type: string + description: | + The tiny URL for this image. By default, this is the image size used for thumbnails beneath the product image on a product page. + date_modified: + type: string + description: | + The date on which the product image was modified. + format: date-time + description: Common ProductImage properties. + x-internal: false + product_Put_Collection: + title: product_Put_Collection + description: The model for batch updating products. + x-internal: false + items: + allOf: + - type: object + properties: + id: + type: integer + description: Unique ID of the *Product*. Read-Only. + readOnly: true + required: + - id + - $ref: '#/components/schemas/product_Base' + x-examples: + example-1: + - id: 0 + name: Smith Journal 13 + type: physical + sku: SM-13 + description: '<p><span>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vel metus ac est egestas porta sed quis erat. Integer id nulla massa. Proin vitae enim nisi. Praesent non dignissim nulla. Nulla mattis id massa ac pharetra. Mauris et nisi in dolor aliquam sodales. Aliquam dui nisl, dictum quis leo sit amet, rutrum volutpat metus. Curabitur libero nunc, interdum ac libero non, tristique porttitor metus. Ut non dignissim lorem, in vestibulum leo. Vivamus sodales quis turpis eget.</span></p>' + weight: 0 + width: 0 + depth: 0 + height: 0 + price: 0 + cost_price: 0 + retail_price: 0 + sale_price: 0 + map_price: 0 + tax_class_id: 0 + product_tax_code: string + categories: + - 0 + brand_id: 0 + inventory_level: 0 + inventory_warning_level: 0 + inventory_tracking: none + fixed_cost_shipping_price: 0 + is_free_shipping: true + is_visible: true + is_featured: true + related_products: + - 0 + warranty: string + bin_picking_number: string + layout_file: string + upc: string + search_keywords: string + availability: available + availability_description: string + gift_wrapping_options_type: list + gift_wrapping_options_list: + - 0 + sort_order: -2147483648 + condition: New + is_condition_shown: true + order_quantity_minimum: 0 + order_quantity_maximum: 0 + page_title: string + meta_keywords: + - string + meta_description: string + view_count: 0 + preorder_release_date: '2019-08-24T14:15:22Z' + preorder_message: string + is_preorder_only: true + is_price_hidden: true + price_hidden_label: string + custom_url: + url: string + is_customized: true + open_graph_type: product + open_graph_title: string + open_graph_description: string + open_graph_use_meta_description: true + open_graph_use_product_name: true + open_graph_use_image: true + brand_name: Common Good + gtin: string + mpn: string + reviews_rating_sum: 3.2 + reviews_count: 4 + total_sold: 80 + custom_fields: + - id: 6 + name: ISBN + value: '1234567890123' + bulk_pricing_rules: + - id: 0 + quantity_min: 10 + quantity_max: 50 + type: price + amount: 10 + images: + - image_file: string + is_thumbnail: true + sort_order: -2147483648 + description: string + image_url: string + id: 0 + product_id: 0 + url_zoom: string + url_standard: string + url_thumbnail: string + url_tiny: string + date_modified: '2019-08-24T14:15:22Z' + videos: + - title: Writing Great Documentation + description: A video about documenation + sort_order: 1 + type: youtube + video_id: z3fRu9pkuXE + id: 0 + product_id: 0 + length: string + type: array + config_Full: + title: config_Full + type: object + properties: + default_value: + type: string + description: | + (date, text, multi_line_text, numbers_only_text) The default value. Shown on a date option as an ISO-8601–formatted string, or on a text option as a string. + checked_by_default: + type: boolean + description: | + (checkbox) Flag for setting the checkbox to be checked by default. + checkbox_label: + type: string + description: | + (checkbox) Label displayed for the checkbox option. + date_limited: + type: boolean + description: | + (date) Flag to limit the dates allowed to be entered on a date option. + date_limit_mode: + type: string + description: | + (date) The type of limit that is allowed to be entered on a date option. + example: range + enum: + - earliest + - range + - latest + date_earliest_value: + type: string + description: | + (date) The earliest date allowed to be entered on the date option, as an ISO-8601 formatted string. + format: date + date_latest_value: + type: string + description: | + (date) The latest date allowed to be entered on the date option, as an ISO-8601 formatted string. + format: date + file_types_mode: + type: string + description: | + (file) The kind of restriction on the file types that can be uploaded with a file upload option. Values: `specific` - restricts uploads to particular file types; `all` - allows all file types. + example: specific + enum: + - specific + - all + file_types_supported: + type: array + description: | + (file) The type of files allowed to be uploaded if the `file_type_option` is set to `specific`. Values: + `images` - Allows upload of image MIME types (`bmp`, `gif`, `jpg`, `jpeg`, `jpe`, `jif`, `jfif`, `jfi`, `png`, `wbmp`, `xbm`, `tiff`). `documents` - Allows upload of document MIME types (`txt`, `pdf`, `rtf`, `doc`, `docx`, `xls`, `xlsx`, `accdb`, `mdb`, `one`, `pps`, `ppsx`, `ppt`, `pptx`, `pub`, `odt`, `ods`, `odp`, `odg`, `odf`). + `other` - Allows file types defined in the `file_types_other` array. + items: + type: string + example: 'images, documents, other' + file_types_other: + type: array + description: | + (file) A list of other file types allowed with the file upload option. + items: + type: string + example: pdf + file_max_size: + type: integer + description: | + (file) The maximum size for a file that can be used with the file upload option. This will still be limited by the server. + example: 5 + text_characters_limited: + type: boolean + description: | + (text, multi_line_text) Flag to validate the length of a text or multi-line text input. + text_min_length: + type: integer + description: | + (text, multi_line_text) The minimum length allowed for a text or multi-line text option. + example: 1 + text_max_length: + type: integer + description: | + (text, multi_line_text) The maximum length allowed for a text or multi line text option. + example: 55 + text_lines_limited: + type: boolean + description: | + (multi_line_text) Flag to validate the maximum number of lines allowed on a multi-line text input. + example: true + text_max_lines: + type: integer + description: | + (multi_line_text) The maximum number of lines allowed on a multi-line text input. + example: 4 + number_limited: + type: boolean + description: | + (numbers_only_text) Flag to limit the value of a number option. + example: true + number_limit_mode: + type: string + description: | + (numbers_only_text) The type of limit on values entered for a number option. + example: lowest + enum: + - lowest + - highest + - range + number_lowest_value: + type: number + description: | + (numbers_only_text) The lowest allowed value for a number option if `number_limited` is true. + example: 100 + number_highest_value: + type: number + description: | + (numbers_only_text) The highest allowed value for a number option if `number_limited` is true. + number_integers_only: + type: boolean + description: | + (numbers_only_text) Flag to limit the input on a number option to whole numbers only. + example: false + product_list_adjusts_inventory: + type: boolean + description: | + (product_list, product_list_with_images) Flag for automatically adjusting inventory on a product included in the list. + product_list_adjusts_pricing: + type: boolean + description: | + (product_list, product_list_with_images) Flag to add the optional product's price to the main product's price. + product_list_shipping_calc: + type: string + description: | + (product_list, product_list_with_images) How to factor the optional product's weight and package dimensions into the shipping quote. Values: `none` - don't adjust; `weight` - use shipping weight only; `package` - use weight and dimensions. + example: weight + enum: + - none + - weight + - package + description: The values for option config can vary based on the Modifier created. + x-internal: false + adjusters_Full: + title: adjusters_Full + type: object + properties: + price: + $ref: '#/components/schemas/adjuster_Full' + weight: + $ref: '#/components/schemas/adjuster_Full' + image_url: + type: string + description: | + The URL for an image displayed on the storefront when the modifier value is selected.Limit of 8MB per file. + example: 'https://cdn8.bigcommerce.com/s-{{store_hash}}/products/184/images/445/naturalcanvascart2_1024x1024__92347__29648.1534344533.1280.1280.jpg?c=2' + purchasing_disabled: + type: object + properties: + status: + type: boolean + description: | + Flag for whether the modifier value disables purchasing when selected on the storefront. This can be used for temporarily disabling a particular modifier value. + message: + type: string + description: | + The message displayed on the storefront when the purchasing disabled status is `true`. + x-internal: false + product_Base: + title: product_Base + type: object + description: |- + Shared `Product` properties used in: + * `POST` + * `PUT` + * `GET` + x-internal: false + x-examples: + example-1: + id: 0 + name: Smith Journal 13 + type: physical + sku: SM-13 + description: '<p><span>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vel metus ac est egestas porta sed quis erat. Integer id nulla massa. Proin vitae enim nisi. Praesent non dignissim nulla. Nulla mattis id massa ac pharetra. Mauris et nisi in dolor aliquam sodales. Aliquam dui nisl, dictum quis leo sit amet, rutrum volutpat metus. Curabitur libero nunc, interdum ac libero non, tristique porttitor metus. Ut non dignissim lorem, in vestibulum leo. Vivamus sodales quis turpis eget.</span></p>' + weight: 0 + width: 0 + depth: 0 + height: 0 + price: 0 + cost_price: 0 + retail_price: 0 + sale_price: 0 + map_price: 0 + tax_class_id: 0 + product_tax_code: string + categories: + - 0 + brand_id: 0 + inventory_level: 0 + inventory_warning_level: 0 + inventory_tracking: none + fixed_cost_shipping_price: 0 + is_free_shipping: true + is_visible: true + is_featured: true + related_products: + - 0 + warranty: string + bin_picking_number: string + layout_file: string + upc: string + search_keywords: string + availability_description: string + availability: available + gift_wrapping_options_type: any + gift_wrapping_options_list: + - 0 + sort_order: -2147483648 + condition: New + is_condition_shown: true + order_quantity_minimum: 0 + order_quantity_maximum: 0 + page_title: string + meta_keywords: + - string + meta_description: string + view_count: 0 + preorder_release_date: '2019-08-24T14:15:22Z' + preorder_message: string + is_preorder_only: true + is_price_hidden: true + price_hidden_label: string + custom_url: + url: string + is_customized: true + open_graph_type: product + open_graph_title: string + open_graph_description: string + open_graph_use_meta_description: true + open_graph_use_product_name: true + open_graph_use_image: true + brand_name: Common Good + gtin: string + mpn: string + reviews_rating_sum: 3.2 + reviews_count: 4 + total_sold: 80 + custom_fields: + - id: 6 + name: ISBN + value: '1234567890123' + bulk_pricing_rules: + - id: 0 + quantity_min: 10 + quantity_max: 50 + type: price + amount: 10 + images: + - image_file: string + is_thumbnail: true + sort_order: -2147483648 + description: string + image_url: string + id: 0 + product_id: 0 + url_zoom: string + url_standard: string + url_thumbnail: string + url_tiny: string + date_modified: '2019-08-24T14:15:22Z' + videos: + - title: Writing Great Documentation + description: A video about documenation + sort_order: 1 + type: youtube + video_id: z3fRu9pkuXE + id: 0 + product_id: 0 + length: string + properties: + name: + maxLength: 250 + minLength: 1 + type: string + description: | + A unique product name. + example: Smith Journal 13 + x-required: + - post + type: + type: string + description: | + The product type. One of: `physical` - a physical stock unit, `digital` - a digital download. + example: physical + enum: + - physical + - digital + x-required: + - post + sku: + maxLength: 255 + minLength: 0 + type: string + description: | + A unique user-defined alphanumeric product code/stock keeping unit (SKU). + example: SM-13 + description: + type: string + description: | + The product description, which can include HTML formatting. + example: '<p><span>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi vel metus ac est egestas porta sed quis erat. Integer id nulla massa. Proin vitae enim nisi. Praesent non dignissim nulla. Nulla mattis id massa ac pharetra. Mauris et nisi in dolor aliquam sodales. Aliquam dui nisl, dictum quis leo sit amet, rutrum volutpat metus. Curabitur libero nunc, interdum ac libero non, tristique porttitor metus. Ut non dignissim lorem, in vestibulum leo. Vivamus sodales quis turpis eget.</span></p>' + weight: + maximum: 9999999999 + minimum: 0 + type: number + description: | + Weight of the product, which can be used when calculating shipping costs. This is based on the unit set on the store + format: float + width: + maximum: 9999999999 + minimum: 0 + type: number + description: | + Width of the product, which can be used when calculating shipping costs. + format: float + depth: + maximum: 9999999999 + minimum: 0 + type: number + description: | + Depth of the product, which can be used when calculating shipping costs. + format: float + height: + maximum: 9999999999 + minimum: 0 + type: number + description: | + Height of the product, which can be used when calculating shipping costs. + format: float + price: + minimum: 0 + type: number + description: | + The price of the product. The price should include or exclude tax, based on the store settings. + format: float + cost_price: + minimum: 0 + type: number + description: | + The cost price of the product. Stored for reference only; it is not used or displayed anywhere on the store. + format: float + retail_price: + minimum: 0 + type: number + description: | + The retail cost of the product. If entered, the retail cost price will be shown on the product page. + format: float + sale_price: + minimum: 0 + type: number + description: | + If entered, the sale price will be used instead of value in the price field when calculating the product's cost. + format: float + map_price: + type: number + description: Minimum Advertised Price + tax_class_id: + maximum: 255 + minimum: 0 + type: number + description: | + The ID of the tax class applied to the product. (NOTE: Value ignored if automatic tax is enabled.) + product_tax_code: + maxLength: 255 + minLength: 0 + type: string + description: | + Tax Codes, such as AvaTax System Tax Codes, identify products and services that fall into special sales-tax categories. By using these codes, merchants who subscribe to a tax provider integration, such as BigCommerce's Avalara Premium, can calculate sales taxes more accurately. Stores without a tax provider will ignore the code when calculating sales tax. Do not pass more than one code. The codes are case-sensitive. For details, please see the tax provider's documentation. + categories: + type: array + description: | + An array of IDs for the categories to which this product belongs. When updating a product, if an array of categories is supplied, all product categories will be overwritten. Does not accept more than 1,000 ID values. + x-required: + - post + items: + type: number + maximum: 1000 + minimum: 0 + brand_id: + maximum: 1000000000 + minimum: 0 + type: integer + description: | + You can add a product to an existing brand during a product /PUT or /POST. Use either the `brand_id` or the `brand_name` field. The response body can include `brand_id`. + brand_name: + type: string + description: You can create the brand during a product PUT or POST request. If the brand already exists, the product /PUT or /POST request adds the product to the brand. If not, the product /PUT or /POST request creates the brand and then adds the product to the brand. Brand name is not case-sensitive; "Common Good" and "Common good" are the same. Use either the `brand_id` or the `brand_name` field. The response body does not include `brand_name`. + example: Common Good + inventory_level: + maximum: 2147483647 + minimum: 0 + type: integer + description: |- + Current inventory level of the product. You must track inventory by _product_ for this to take effect (see the `inventory_tracking` field). The Catalog API returns the inventory for only the default location. + + The inventory for a product cannot exceed 2,147,483,647 in the catalog. If you exceed the limit, the store sets the inventory level to the limit. + + The Catalog API handles limits in a different way than the Inventory API. For more information, see [Limit handling](/docs/store-operations/catalog/inventory-adjustments#limit-handling-in-inventory-versus-catalog-api). + inventory_warning_level: + maximum: 2147483647 + minimum: 0 + type: integer + description: | + Inventory warning level for the product. When the product's inventory level drops below the warning level, the store owner will be informed. Simple inventory tracking must be enabled (see the `inventory_tracking` field) for this to take any effect. + inventory_tracking: + type: string + description: | + The type of inventory tracking for the product. Values are: `none` - inventory levels will not be tracked; `product` - inventory levels will be tracked using the `inventory_level` and `inventory_warning_level` fields; `variant` - inventory levels will be tracked based on variants, which maintain their own warning levels and inventory levels. + enum: + - none + - product + - variant + fixed_cost_shipping_price: + minimum: 0 + type: number + description: | + A fixed shipping cost for the product. If defined, this value will be used during checkout instead of normal shipping-cost calculation. + format: float + is_free_shipping: + type: boolean + description: | + Flag used to indicate whether the product has free shipping. If `true`, the shipping cost for the product will be zero. + is_visible: + type: boolean + description: | + Flag to determine whether the product should be displayed to customers browsing the store. If `true`, the product will be displayed. If `false`, the product will be hidden from view. + is_featured: + type: boolean + description: | + Flag to determine whether the product should be included in the `featured products` panel when viewing the store. + related_products: + type: array + description: | + An array of IDs for the related products. + items: + type: integer + warranty: + maxLength: 65535 + minLength: 0 + type: string + description: | + Warranty information displayed on the product page. Can include HTML formatting. + bin_picking_number: + maxLength: 255 + minLength: 0 + type: string + description: | + The BIN picking number for the product. + layout_file: + maxLength: 500 + minLength: 0 + type: string + description: | + The layout template file used to render this product category. This field is writable only for stores with a Blueprint theme applied. For stores with a Stencil theme applied, see [Custom Template Associations](/docs/rest-content/custom-template-associations). + upc: + type: string + maxLength: 32 + minLength: 0 + description: | + The product UPC code, which is used in feeds for shopping comparison sites and external channel integrations. + search_keywords: + maxLength: 65535 + minLength: 0 + type: string + description: | + A comma-separated list of keywords that can be used to locate the product when searching the store. + availability_description: + maxLength: 255 + minLength: 0 + type: string + description: | + Availability text displayed on the checkout page, under the product title. Tells the customer how long it will normally take to ship this product, such as: 'Usually ships in 24 hours.' + availability: + type: string + description: | + Availability of the product. (Corresponds to the product's [Purchasability](https://support.bigcommerce.com/s/article/Adding-Products-v3?language=en_US#sections) section in the control panel.) Supported values: `available` - the product is available for purchase; `disabled` - the product is listed on the storefront, but cannot be purchased; `preorder` - the product is listed for pre-orders. + enum: + - available + - disabled + - preorder + gift_wrapping_options_type: + type: string + description: | + Type of gift-wrapping options. Values: `any` - allow any gift-wrapping options in the store; `none` - disallow gift-wrapping on the product; `list` – provide a list of IDs in the `gift_wrapping_options_list` field. + + Always included in the response body; not applicable for the `include_fields` and `exclude_fields` query parameters. + enum: + - any + - none + - list + gift_wrapping_options_list: + type: array + description: | + A list of gift-wrapping option IDs. + + Always included in the response body; not applicable for the `include_fields` and `exclude_fields` query parameters. + items: + type: integer + sort_order: + type: integer + description: | + Priority to give this product when included in product lists on category pages and in search results. Lower integers will place the product closer to the top of the results. + maximum: 2147483647 + minimum: -2147483648 + condition: + type: string + description: | + The product condition. Will be shown on the product page if the `is_condition_shown` field's value is `true`. Possible values: `New`, `Used`, `Refurbished`. + enum: + - New + - Used + - Refurbished + is_condition_shown: + type: boolean + description: | + Flag used to determine whether the product condition is shown to the customer on the product page. + order_quantity_minimum: + maximum: 1000000000 + minimum: 0 + type: integer + description: | + The minimum quantity an order must contain, to be eligible to purchase this product. + order_quantity_maximum: + maximum: 1000000000 + minimum: 0 + type: integer + description: | + The maximum quantity an order can contain when purchasing the product. + page_title: + maxLength: 255 + minLength: 0 + type: string + description: | + Custom title for the product page. If not defined, the product name will be used as the meta title. + meta_keywords: + type: array + maxLength: 65535 + minLength: 0 + description: | + Custom meta keywords for the product page. If not defined, the store's default keywords will be used. + items: + type: string + meta_description: + maxLength: 65535 + minLength: 0 + type: string + description: | + Custom meta description for the product page. If not defined, the store's default meta description will be used. + view_count: + maximum: 1000000000 + minimum: 0 + type: integer + description: | + The number of times the product has been viewed. + deprecated: true + preorder_release_date: + type: string + description: | + Pre-order release date. See the `availability` field for details on setting a product's availability to accept pre-orders. + format: date-time + nullable: true + preorder_message: + maxLength: 255 + minLength: 0 + type: string + description: | + Custom expected-date message to display on the product page. If undefined, the message defaults to the storewide setting. Can contain the `%%DATE%%` placeholder, which will be substituted for the release date. + is_preorder_only: + type: boolean + description: | + If set to true then on the preorder release date the preorder status will automatically be removed. + If set to false, then on the release date the preorder status **will not** be removed. It will need to be changed manually either in the + control panel or using the API. Using the API set `availability` to `available`. + is_price_hidden: + type: boolean + description: | + False by default, indicating that this product's price should be shown on the product page. If set to `true`, the price is hidden. (NOTE: To successfully set `is_price_hidden` to `true`, the `availability` value must be `disabled`.) + price_hidden_label: + maxLength: 200 + minLength: 0 + type: string + description: | + By default, an empty string. If `is_price_hidden` is `true`, the value of `price_hidden_label` is displayed instead of the price. (NOTE: To successfully set a non-empty string value with `is_price_hidden` set to `true`, the `availability` value must be `disabled`.) + custom_url: + $ref: '#/components/schemas/customUrl_Full' + open_graph_type: + type: string + description: | + Type of product, defaults to `product`. + enum: + - product + - album + - book + - drink + - food + - game + - movie + - song + - tv_show + open_graph_title: + type: string + description: | + Title of the product, if not specified the product name will be used instead. + open_graph_description: + type: string + description: | + Description to use for the product, if not specified then the meta_description will be used instead. + open_graph_use_meta_description: + type: boolean + description: | + Flag to determine if product description or open graph description is used. + open_graph_use_product_name: + type: boolean + description: | + Flag to determine if product name or open graph name is used. + open_graph_use_image: + type: boolean + description: | + Flag to determine if product image or open graph image is used. + gtin: + type: string + description: Global Trade Item Number + mpn: + type: string + description: Manufacturer Part Number + reviews_rating_sum: + type: integer + description: | + The total (cumulative) rating for the product. + example: 3 + reviews_count: + type: integer + description: | + The number of times the product has been rated. + example: 4 + total_sold: + type: integer + description: | + The total quantity of this product sold. + example: 80 + custom_fields: + type: array + minimum: 0 + maximum: 255 + description: 200 maximum custom fields per product. 255 maximum characters per custom field. The default rate limit for this endpoint is 40 concurrent requests. + items: + $ref: '#/components/schemas/productCustomField_Put' + bulk_pricing_rules: + type: array + items: + allOf: + - type: object + properties: + id: + type: integer + description: Unique ID of the *Bulk Pricing Rule*. Read-Only. + readOnly: true + required: + - id + - $ref: '#/components/schemas/bulkPricingRule_Full' + images: + type: array + items: + $ref: '#/components/schemas/productImage_Full' + videos: + type: array + items: + $ref: '#/components/schemas/productVideo_Full' + variants: + type: array + items: + $ref: '#/components/schemas/productVariant_Full' + required: + - name + - type + - weight + - price + metafield_Full: + title: metafield_Full + allOf: + - type: object + properties: + id: + type: integer + description: Unique ID of the *Metafield*. Read-Only. + readOnly: true + example: 6 + - $ref: '#/components/schemas/metafield_Base' + - type: object + properties: + resource_type: + type: string + description: | + The type of resource with which the metafield is associated. + example: product + enum: + - category + - brand + - product + - variant + x-required: + - post + resource_id: + maximum: 10000000000 + minimum: 0 + type: integer + description: | + The ID of the resource with which the metafield is associated. + example: 111 + x-required: + - post + date_created: + type: string + description: | + Date and time of the metafield's creation. Read-Only. + readOnly: true + format: date-time + example: '2018-05-07T20:14:17+00:00' + date_modified: + type: string + description: | + Date and time when the metafield was last updated. Read-Only. + readOnly: true + format: date-time + example: '2018-05-07T20:14:17+00:00' + x-internal: false + errorResponse_409: + title: errorResponse_409 + allOf: + - type: object + properties: + code: + type: integer + status: + type: integer + title: + type: string + description: The error title describing the particular error. + type: + type: string + - type: object + properties: + errors: + $ref: '#/components/schemas/DetailedErrors' + x-internal: false + errorResponse_422: + title: errorResponse_422 + allOf: + - type: object + properties: + code: + type: integer + status: + type: integer + title: + type: string + description: The error title describing the particular error. + type: + type: string + - type: object + properties: + errors: + $ref: '#/components/schemas/DetailedErrors' + x-internal: false + MetaPaginationObject: + type: object + properties: + pagination: + type: object + properties: + total: + type: integer + example: 246 + minimum: 0 + count: + type: integer + example: 5 + minimum: 0 + per_page: + type: integer + example: 5 + minimum: 0 + current_page: + type: integer + example: 1 + minimum: 1 + total_pages: + type: integer + example: 50 + minimum: 0 + links: + type: object + properties: + next: + type: string + example: '?limit=5&page=2' + current: + type: string + example: '?limit=5&page=1' + x-tags: + - Models + BaseError: + type: object + description: | + Error payload for the BigCommerce API. + properties: + status: + description: | + The HTTP status code. + type: integer + title: + description: | + The error title describing the particular error. + type: string + type: + type: string + instance: + type: string + x-tags: + - Models + ProductChannelAssignment: + properties: + product_id: + type: integer + channel_id: + type: integer + x-tags: + - Models + ProductCategoryAssignment: + properties: + product_id: + type: integer + category_id: + type: integer + x-tags: + - Models + beta5DetailedErrors: + type: object + properties: {} + additionalProperties: true + x-tags: + - Models + beta5ErrorResponse: + allOf: + - $ref: '#/components/schemas/BaseError' + - type: object + properties: + errors: + $ref: '#/components/schemas/beta5DetailedErrors' + x-tags: + - Models + parameters: + ProductIdParam: + name: product_id + in: path + description: | + The ID of the `Product` to which the resource belongs. + required: true + schema: + type: integer + ReviewIdParam: + name: review_id + description: | + The ID of the `review` that is being operated on. + required: true + in: path + schema: + type: integer + ImageIdParam: + name: image_id + description: | + The ID of the `Image` that is being operated on. + required: true + in: path + schema: + type: integer + MetafieldIdParam: + name: metafield_id + in: path + description: | + The ID of the `Metafield`. + required: true + schema: + type: integer + VideoIdParam: + name: id + description: The BigCommerce ID of the `Video` + required: true + in: path + schema: + type: integer + ComplexRuleIdParam: + name: complex_rule_id + description: | + The ID of the `ComplexRule`. + required: true + in: path + schema: + type: integer + CustomFieldIdParam: + name: custom_field_id + description: | + The ID of the `CustomField`. + required: true + in: path + schema: + type: integer + BulkPricingRuleIdParam: + name: bulk_pricing_rule_id + description: | + The ID of the `BulkPricingRule`. + required: true + in: path + schema: + type: integer + Accept: + name: Accept + in: header + required: true + description: 'The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body.' + schema: + type: string + default: 'application/json' + ContentType: + name: Content-Type + in: header + required: true + description: 'The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the request body.' + schema: + type: string + default: 'application/json' + securitySchemes: + X-Auth-Token: + name: X-Auth-Token + description: |- + ### OAuth scopes + + | UI Name | Permission | Parameter | + |:--------|:-----------|:----------| + | Products | modify | `store_v2_products` | + | Products | read-only | `store_v2_products_read_only` | + + ### Authentication header + + | Header | Argument | Description | + |:-------|:---------|:------------| + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | + + ### Further reading + + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). + + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). + + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). + type: apiKey + in: header diff --git a/reference/channels.v3.yml b/reference/channels.v3.yml index 50611fbb4..43289ecd0 100644 --- a/reference/channels.v3.yml +++ b/reference/channels.v3.yml @@ -8,7 +8,7 @@ info: email: support@bigcommerce.com title: Channels description: |- - Create and manage sales [channels](/api-docs/channels/overview), their [sites](/docs/rest-management/channels/channel-site), and their [product listings](/docs/rest-management/channels/channel-listings). + Create and manage sales [channels](/docs/integrations/channels), their [sites](/docs/rest-management/channels/channel-site), and their [product listings](/docs/rest-management/channels/channel-listings). ## Channels @@ -18,34 +18,43 @@ info: A channel's `type` and `platform` combination must be a valid pair as indicated in the table below. - | Platform | Accepted Type | - |-------------------|---------------------------| - | `square` | `pos` | - | `stripe` | `pos` | - | `vend` | `pos` | - | `clover` | `pos` | - | `talech` | `pos` | - | `facebook by meta`| `marketplace`,`marketing` | - | `instagram by meta`| `marketplace`,`marketing`| - | `amazon` | `marketplace` | - | `ebay` | `marketplace` | - | `pinterest` | `marketplace` | - | `wayfair` | `marketplace` | - | `overstock` | `marketplace` | - | `etsy` | `marketplace` | - | `wish` | `marketplace` | - | `walmart` | `marketplace` | - | `bigcommerce` | `storefront` | - | `gatsby` | `storefront` | - | `wordpress` | `storefront` | - | `drupal` | `storefront` | - | `acquia` | `storefront` | - | `bloomreach` | `storefront` | - | `deity` | `storefront` | - | `next` | `storefront` | - | `vue` | `storefront` | - | `google_shopping` | `marketing` | - | `custom` | `storefront`, `pos`, `marketing`, `marketplace` | + | Platform | Accepted Type | + |:--------------------|:--------------| + | `clover` | `pos` | + | `square` | `pos` | + | `stripe` | `pos` | + | `talech` | `pos` | + | `vend` | `pos` | + | `amazon` | `marketplace` | + | `belk` | `marketplace` | + | `catch` | `marketplace` | + | `ebay` | `marketplace` | + | `etsy` | `marketplace` | + | `facebook` | `marketplace`, `marketing` | + | `hudsons_bay` | `marketplace` | + | `google` | `marketplace`, `marketing` | + | `google_shopping` (deprecated) | `marketing` | + | `instagram` | `marketplace`, `marketing` | + | `macys` | `marketplace` | + | `mirakl` | `marketplace` | + | `overstock` | `marketplace` | + | `pinterest` | `marketplace` | + | `target_plus` | `marketplace` | + | `tiktok` | `marketplace` | + | `wayfair` | `marketplace` | + | `wish` | `marketplace` | + | `walmart` | `marketplace` | + | `acquia` | `storefront` | + | `bigcommerce` | `storefront` | + | `bloomreach` | `storefront` | + | `deity` | `storefront` | + | `drupal` | `storefront` | + | `gatsby` | `storefront` | + | `next` | `storefront` | + | `vue` | `storefront` | + | `wordpress` | `storefront` | + | `custom` | `storefront`, `pos`, `marketing`, `marketplace` | + ### Status @@ -72,9 +81,9 @@ info: ## Resources * [Sites and Routes API Reference](/docs/rest-management/sites) - * [Building Channels Overview](/api-docs/channels/overview) - * [Building Channel Apps](/api-docs/channels/building-channel-apps) - * [Channels Toolkit Reference](/api-docs/channels/channels-toolkit-reference) + * [Building Channels Overview](/docs/integrations/channels) + * [Building Channel Apps](/docs/integrations/channels/guide) + * [Channels Toolkit Reference](/docs/integrations/channels/toolkit-reference) servers: - url: 'https://api.bigcommerce.com/stores/{store_hash}/v3' variables: @@ -243,7 +252,7 @@ paths: - $ref: '#/components/parameters/ContentType' summary: Create Multiple Channels Currency Assignments operationId: createMultipleChannelsCurrencyAssignments - description: Sets enabled currencies and default currency for multiple channels. Note that currencies must be added first in the **Settings > Setup > Currencies** settings from an active MSF-enabled BigCommerce Control Panel before the currencies can be assigned to a channel. + description: Sets enabled currencies and default currency for multiple channels. Note that currencies must be added first in the **Settings > Setup > Currencies** settings from an active MSF-enabled BigCommerce store control panel before the currencies can be assigned to a channel. requestBody: content: application/json: @@ -265,7 +274,7 @@ paths: parameters: - $ref: '#/components/parameters/ContentType' operationId: updateMultipleChannelsCurrencyAssignments - description: Updates enabled currencies and default currency for multiple channels. Note that currencies must be added first in the **Settings > Setup > Currencies** settings from an active MSF-enabled BigCommerce Control Panel before the currencies can be assigned to a channel. + description: Updates enabled currencies and default currency for multiple channels. Note that currencies must be added first in the **Settings > Setup > Currencies** settings from an active MSF-enabled BigCommerce store control panel before the currencies can be assigned to a channel. requestBody: content: application/json: @@ -302,7 +311,7 @@ paths: parameters: - $ref: '#/components/parameters/ContentType' operationId: createSingleChannelCurrencyAssignments - description: Sets enabled currencies and default currency for a specific channel. Note that currencies must be added first in the **Settings > Setup > Currencies** settings from an active MSF-enabled BigCommerce Control Panel before the currencies can be assigned to a channel. + description: Sets enabled currencies and default currency for a specific channel. Note that currencies must be added first in the **Settings > Setup > Currencies** settings from an active MSF-enabled BigCommerce store control panel before the currencies can be assigned to a channel. requestBody: content: application/json: @@ -324,7 +333,7 @@ paths: parameters: - $ref: '#/components/parameters/ContentType' operationId: updateSingleChannelCurrencyAssignments - description: Updates enabled currencies and default currency for a specific channel. Note that currencies must be added first in the **Settings > Setup > Currencies** settings from an active MSF-enabled BigCommerce Control Panel before the currencies can be assigned to a channel. + description: Updates enabled currencies and default currency for a specific channel. Note that currencies must be added first in the **Settings > Setup > Currencies** settings from an active MSF-enabled BigCommerce store control panel before the currencies can be assigned to a channel. requestBody: content: application/json: @@ -686,10 +695,10 @@ paths: operationId: get-channels-channel_id-metafields parameters: - $ref: '#/components/parameters/PageParam' - - $ref: ./catalog.v3.yml#/components/parameters/LimitParam - - $ref: ./catalog.v3.yml#/components/parameters/MetafieldKeyParam + - $ref: '#/components/parameters/LimitParam' + - $ref: '#/components/parameters/MetafieldKeyParam' - $ref: '#/components/parameters/MetafieldNamespaceParam' - - $ref: ./catalog.v3.yml#/components/parameters/DirectionParam + - $ref: '#/components/parameters/DirectionParam' description: Returns a list of metafields on a channel. Optional filter parameters can be passed in. post: summary: Create a Channel Metafield @@ -987,6 +996,9 @@ components: $ref: '#/components/schemas/ChannelWithoutCurrencies' meta: $ref: '#/components/schemas/MetaWithFullPagination' + required: + - data + - meta examples: response: $ref: '#/components/examples/multiple_channels_without_currencies_resp_example' @@ -1131,7 +1143,7 @@ components: type: object properties: bigcommerce_protected_app_sections: - $ref: '#/components/schemas/BigcommerceProtectedAppSections' + $ref: '#/components/schemas/BigCommerceProtectedAppSections' custom_app_sections: $ref: '#/components/schemas/CustomAppSections' meta: @@ -1168,6 +1180,8 @@ components: $ref: '#/components/examples/error_422_channel_resp_example' Invalid Type and Platform Combination: $ref: '#/components/examples/error_422_invalid_type_platform_combination_resp_example' + Invalid Channel Name: + $ref: '#/components/examples/error_422_invalid_channel_name_resp_example' channel_not_found_resp: description: A *Channel* with the provided ID was not found. content: @@ -1224,6 +1238,8 @@ components: $ref: '#/components/examples/error_422_prevent_update_type_and_platform_resp_example' Update Deleted Channel Error: $ref: '#/components/examples/error_422_prevent_update_deleted_channel_resp_example' + Update Channel Name Error: + $ref: '#/components/examples/error_422_invalid_channel_name_resp_example' missing_or_invalid_multiple_channels_currency_assignments_data_resp: description: The request is missing one or more required fields or invalid data is submitted. content: @@ -1296,7 +1312,7 @@ components: content: application/json: schema: - description: 'Metafield for products, categories, variants, and brands. The max number of metafields allowed on each product, category, variant, or brand is fifty. For more information, see [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center.' + description: 'Metafield for products, categories, variants, and brands. The max number of metafields allowed on each product, category, variant, or brand is 250. For more information, see [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center.' x-internal: false type: object properties: @@ -1921,6 +1937,12 @@ components: title: A deleted channel cannot be updated. Channel can be restored within 90 days after deleting by contacting BigCommerce support team type: /api-docs/getting-started/api-status-codes errors: {} + error_422_invalid_channel_name_resp_example: + value: + status: 422 + title: Only latin alphabet letters, arabic numerals, dash and underscore are allowed to be used as channel name. + type: /api-docs/getting-started/api-status-codes + errors: {} error_422_multiple_channels_currency_assignments_resp_example: value: status: 422 @@ -2013,15 +2035,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header schemas: @@ -2184,7 +2206,7 @@ components: example-1: active ChannelName: type: string - description: Name of the channel as it will appear to merchants in the control panel. + description: Name of the channel as it will appear in the store control panel. The only characters it can include are Latin alphabet letters, Arabic numerals, dashes, and underscores. x-internal: false x-examples: example-1: string @@ -2300,11 +2322,11 @@ components: properties: app: type: object - description: 'A [channel app](/api-docs/channels/overview#channel-apps) config object for optionally configuring the channelʼs user interface in the control panel.' + description: 'A [channel app](/docs/integrations/channels#channel-apps) config object for optionally configuring the channelʼs user interface in the control panel.' properties: id: type: integer - description: 'The unique `id` given to an app registered in [DevTools](https://devtools.bigcommerce.com/); used to create links to the app in channel manager. `app.id` is optional; however, if youʼre building an app that creates or manages a channel, we recommend including it to ensure the user interface in the control panel works properly. Select partners who are promoted in the Channel Manager must build an app, and include the app ID in the create channel request. [Learn how to find an Appʼs ID](/api-docs/apps/tutorials/id).' + description: 'The unique `id` given to an app registered in [DevTools](https://devtools.bigcommerce.com/); used to create links to the app in channel manager. `app.id` is optional; however, if youʼre building an app that creates or manages a channel, we recommend including it to ensure the user interface in the control panel works properly. Select partners who are promoted in the Channel Manager must build an app, and include the app ID in the create channel request. [Learn how to find an Appʼs ID](/docs/integrations/apps/guide/id).' sections: type: array description: 'Sections are now deprecated under config_meta. The new /channel-menus endpoints should be used instead. If set, when the app is loaded within the control panel, the navigation `sections` will be directly embedded in the control panel navigation.' @@ -2558,6 +2580,9 @@ components: $ref: '#/components/schemas/ChannelDateModified' icon_url: $ref: '#/components/schemas/IconUrl' + required: + - id + - name x-internal: false ChannelWithCurrencies: type: object @@ -2632,9 +2657,9 @@ components: items: $ref: '#/components/schemas/ChannelProductVariantFull' x-internal: false - BigcommerceProtectedAppSections: + BigCommerceProtectedAppSections: type: array - description: 'List of pre-built UI pages an app developer can choose to enable for a channel. More information can be found [here](https://developer.bigcommerce.com/docs/ZG9jOjM4MzMyMzA-building-storefront-channels#protected-ui-sections)' + description: 'List of channel-specific control panel menu navigation items and corresponding settings pages an app developer can choose to enable for the subject channel. Protected settings override any settings set in those UI sections at the storewide level. Learn more in the [Building Storefront Channels](/docs/integrations/channels/guide/storefronts#protected-ui-sections) tutorial.' items: type: string enum: @@ -2648,7 +2673,7 @@ components: type: object properties: bigcommerce_protected_app_sections: - $ref: '#/components/schemas/BigcommerceProtectedAppSections' + $ref: '#/components/schemas/BigCommerceProtectedAppSections' custom_app_sections: $ref: '#/components/schemas/CustomAppSections' CustomAppSections: @@ -2658,10 +2683,10 @@ components: properties: title: type: string - description: Text displayed to the merchant + description: Text displayed to the merchant. query_path: type: string - description: Value used in the `section` query param + description: Value used in the `section` query param. x-internal: false Error: type: object @@ -2925,7 +2950,7 @@ components: metafield_Post: title: metafield_Post type: object - description: 'Metafield for products, categories, variants, and brands. The max number of metafields allowed on each product, category, variant, or brand is fifty. For more information, see [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center.' + description: 'Metafield for products, categories, variants, and brands. The max number of metafields allowed on each product, category, variant, or brand is 250. For more information, see [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center.' x-internal: false properties: namespace: @@ -2987,7 +3012,7 @@ components: metafield_Put: title: metafield_Put type: object - description: 'Metafield for products, categories, variants, and brands. The max number of metafields allowed on each product, category, variant, or brand is fifty. For more information, see [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center.' + description: 'Metafield for products, categories, variants, and brands. The max number of metafields allowed on each product, category, variant, or brand 250. For more information, see [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center.' x-internal: false properties: namespace: @@ -3040,5 +3065,4 @@ components: type: string description: | Description for the metafield. - example: Location in the warehouse - + example: Location in the warehouse. \ No newline at end of file diff --git a/reference/checkouts.sf.yml b/reference/checkouts.sf.yml index e10feecc3..2d72c25b2 100644 --- a/reference/checkouts.sf.yml +++ b/reference/checkouts.sf.yml @@ -5,9 +5,9 @@ info: Manage checkout operations and data using front-end JavaScript on BigCommerce Stencil-powered storefronts. - For info about API accounts, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). + For info about API accounts, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). - For info about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#same-origin-cors-authentication). + For info about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#same-origin-cors-authentication). version: '' termsOfService: 'https://www.bigcommerce.com/terms' contact: @@ -373,11 +373,12 @@ paths: description: |- Updates a *Checkout Line Item*. Updates an existing, single line item in the cart. - If a variant needs to be changed or updated, the product will need to be removed and re-added to the cart with the correct variants using the [Add Cart Line Items](/docs/rest-storefront/carts/cart-items#add-cart-line-items) endpoint. + If a variant needs to be changed or updated, the product will need to be removed and re-added to the cart with the correct variants using the [Add Cart Line Items](/docs/rest-storefront/carts/cart-items#add-cart-line-items) endpoint or the [GraphQL Storefront API](/docs/storefront/cart-checkout/guide/graphql-storefront). - > #### Note + > #### Notes > * Substitute your storefront domain for `yourstore.example.com`. - > * The Send a Test Request feature is not currently supported for this endpoint. + > * The Send a Test Request feature is not currently supported for this endpoint. + > * Please note that this API endpoint is not concurrent safe, meaning multiple simultaneous requests could result in unexpected and inconsistent results. operationId: CheckoutsCartsItemsItemIdByCheckoutIdAndCartIdPut parameters: - name: checkoutId @@ -1201,7 +1202,7 @@ paths: * Required Fields: * `shipping_address` (deprecated) or `address` * `lineItems` - 2. [Update the Consignment](/api-reference/storefront/checkouts/checkout-consignments/checkoutsconsignmentsbycheckoutidandconsignmentidput) with Shipping Options. + 2. Update the Consignment with Shipping Options using the [REST Storefront API](/checkouts/checkout-consignments#update-a-consignment), the [REST Management API](/docs/rest-management/checkouts/checkout-consignments#update-checkout-consignment) or the [GraphQL Storefront API](/docs/storefront/cart-checkout/guide/graphql-storefront). ### For **pickup** consignments: 1. Create a new consignment object. @@ -1211,11 +1212,12 @@ paths: * `pickupOption` * `lineItems` - To learn more about creating a Checkout Consignment, see the [Carts and Checkouts Tutorial](/api-docs/storefront/tutorials/carts). + To learn more about creating a Checkout Consignment, see the [Carts and Checkouts Tutorial](/docs/storefront/cart-checkout/guide/rest-storefront). - > #### Note + > #### Notes > * Substitute your storefront domain for `yourstore.example.com`. - > * The Send a Test Request feature is not currently supported for this endpoint. + > * The Send a Test Request feature is not currently supported for this endpoint. + > * Please note that this API endpoint is not concurrent safe, meaning multiple simultaneous requests could result in unexpected and inconsistent results. operationId: CheckoutsConsignmentsByCheckoutIdPost parameters: - name: checkoutId @@ -1379,12 +1381,13 @@ paths: * `shippingOptionId` or `pickupOptionId` * `lineItems` - To learn more about creating a Checkout Consignment see [Checkout Consignment API](/api-docs/checkouts/checkout-consignment). + To learn more about creating a Checkout Consignment see [Checkout Consignment API](/docs/storefront/cart-checkout/guide/consignments). - > #### Note + > #### Notes > * You cannot pass both an `address` and a `shippingOptionId` because the shipping option may not be available for the new address > * Substitute your storefront domain for `yourstore.example.com`. - > * The Send a Test Request feature is not currently supported for this endpoint. + > * The Send a Test Request feature is not currently supported for this endpoint. + > * Please note that this API endpoint is not concurrent safe, meaning multiple simultaneous requests could result in unexpected and inconsistent results. operationId: CheckoutsConsignmentsByCheckoutIdAndConsignmentIdPut parameters: - name: checkoutId @@ -2771,7 +2774,7 @@ components: description: The discounted amount applied within a given context. format: double lineItems: - type: array + type: object description: '' items: title: Line Item @@ -2838,10 +2841,16 @@ components: type: number description: The total value of all discounts applied to this item (excluding coupon). format: double + brand: + type: string + description: The product's brand. couponAmount: type: number description: The total value of all coupons applied to this item. format: double + originalPrice: + type: number + description: The item’s original price is the same as the product’s default price. listPrice: type: number description: The item’s list price, as quoted by the manufacturer or distributor. @@ -2951,6 +2960,9 @@ components: type: number description: The total value of all coupons applied to this item. format: double + originalPrice: + type: number + description: The item’s original price is the same as the product’s default price. listPrice: type: number description: The item’s list price, as quoted by the manufacturer or distributor. @@ -3417,6 +3429,8 @@ components: type: number description: '' format: double + giftWrapping: + $ref: '#/components/schemas/cartLineItemGiftWrapping_Put' x-internal: false cartLineItemGiftCertificate_Put: title: cartLineItemGiftCertificate_Put @@ -3449,6 +3463,39 @@ components: description: '' format: double x-internal: false + cartLineItemGiftWrapping_Put: + title: Gift Wrapping Request Data + required: + - wrapTogether + - wrapDetails + type: object + nullable: true + description: if passing null, it will remove the current gift wrapping for the item + properties: + wrapTogether: + type: boolean + description: Boolean value that specifies whether items whether items should be wrapped together or wrapped individually. + example: true + wrapDetails: + type: array + description: |- + Details for the gift wrapping option selected. This can be specified for each line item or together based on wrapTogether value. + If wrapTogether is false, each element in the wrapDetails array determines each item's specific wrapping. + (e.g if this line item has 6 quantity, you can pass at maximum 6 elements for the array to spefified each one's wrapping) + If wrapTogether is true, we will only use 1st element in the wrapDetails array to determine what to be wrapped + items: + type: object + required: + - id + properties: + id: + type: integer + description: Identifier of the gift wrapping option selected. + example: 0 + message: + type: string + description: Custom gift message. + example: Happy Birthday CreateConsignmentRequest: title: Create Consignment Request type: object diff --git a/reference/checkouts.v3.yml b/reference/checkouts.v3.yml index 9b9abd3f7..a15e535ea 100644 --- a/reference/checkouts.v3.yml +++ b/reference/checkouts.v3.yml @@ -2,7 +2,7 @@ openapi: '3.0.3' info: title: Checkouts description: |- - For more information on authenticating BigCommerce APIs, see [Authentication](/api-docs/getting-started/authentication). + For more information on authenticating BigCommerce APIs, see [Authentication](/docs/start/authentication). Create and manage checkouts from existing carts using BigCommerce checkout logic. version: '3.0' @@ -1598,7 +1598,6 @@ paths: AllowDynamicQueryParameters: false AllowDynamicFormParameters: false IsMultiContentStreaming: false - x-codegen-request-body-name: body '/checkouts/{checkoutId}/discounts': post: tags: @@ -2383,7 +2382,6 @@ paths: - homepage - cartpage text: Some text - x-codegen-request-body-name: body '/checkouts/{checkoutId}/billing-address': post: tags: @@ -3154,7 +3152,6 @@ paths: AllowDynamicQueryParameters: false AllowDynamicFormParameters: false IsMultiContentStreaming: false - x-codegen-request-body-name: body '/checkouts/{checkoutId}/billing-address/{addressId}': put: tags: @@ -3925,7 +3922,6 @@ paths: AllowDynamicQueryParameters: false AllowDynamicFormParameters: false IsMultiContentStreaming: false - x-codegen-request-body-name: body '/checkouts/{checkoutId}/consignments': post: tags: @@ -3934,7 +3930,10 @@ paths: description: |- Adds a new consignment to a checkout. - For more information about working with consignments, see [Checkout consignment](/api-docs/checkouts/checkout-consignment). + + Please note that this API endpoint is not concurrent safe, meaning multiple simultaneous requests could result in unexpected and inconsistent results. + + For more information about working with consignments, see [Checkout consignment](/docs/storefront/cart-checkout/guide/consignments). Though the only required `address` properties to create a consignment are `email` and `country_code`, to successfully [create an order](/docs/rest-management/checkouts/checkout-orders#create-an-order) the `address` requires the following properties: * `first_name` @@ -3964,8 +3963,36 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/CreateConsignmentRequest' - required: true + $ref: '#/components/schemas/CreateConsignmentRequest' + examples: + Shipping Consignment: + value: + - address: + first_name: "Jane" + last_name: "Doe" + email: "Jane.Doe@email.com" + company: "BigCommerce" + address1: "100 Main Street" + address2: "string" + city: "Austin" + state_or_province: "Texas" + state_or_province_code: "string" + country_code: "US" + postal_code: "78701" + phone: "555-555-5555" + custom_fields: + - field_id: "string" + field_value: "string" + line_items: + item_id: "118f8774-387c-485e-a095-6ef76d5f1bbd" + quantity: 1 + Pickup Consignment: + value: + - line_items: + - item_id: "118f8774-387c-485e-a095-6ef76d5f1bbd" + quantity: 1 + pickup_option: + pickup_method_id: 1 responses: '200': description: '' @@ -4714,7 +4741,6 @@ paths: AllowDynamicQueryParameters: false AllowDynamicFormParameters: false IsMultiContentStreaming: false - x-codegen-request-body-name: body '/checkouts/{checkoutId}/consignments/{consignmentId}': parameters: @@ -4730,13 +4756,18 @@ paths: - Checkout Consignments summary: Update Checkout Consignment description: |- - Updates an existing consignment. The address, line item IDs, and the shipping option ID can be updated using this endpoint. + Updates an existing consignment. The address, line item IDs, and shipping option ID can be updated using this endpoint. + + Use a separate `PUT` request to update the shipping option IDs if you also want to update the address and line item IDs. - To add a new address and shipping options with line items, complete the following steps. + To add new shipping options, complete the following steps: + * Use the [Add Consignment to Checkout](/docs/rest-management/checkouts/checkout-consignments#add-consignment-to-checkout) endpoint to add a new [consignment] to a checkout. + * Assign a shipping option to the new consignment by sending a `PUT` request to update the consignment's `shipping_option_id` with a returned value from `data.consignments[N].available_shipping_option[N].id` obtained in the [Add Consignment to Checkout](/docs/rest-management/checkouts/checkout-consignments#add-consignment-to-checkout) endpoint. - 1. Add a new [consignment](/docs/rest-management/checkouts/checkout-consignments#add-consignment-to-checkout) to a checkout. + To update an existing address and line item IDs, assign a new address and line item IDs by sending a `PUT` request. + + Please note that this API endpoint is not concurrent safe, meaning multiple simultaneous requests could result in unexpected and inconsistent results. - 2. Assign a shipping option to the new consignment by sending a `PUT` request to update the consignment's `shipping_option_id` with a returned value from `data.consignments[N].available_shipping_option[N].id` obtained in Step One. operationId: CheckoutsConsignmentsByCheckoutIdAndConsignmentIdPut parameters: - $ref: '#/components/parameters/Content-Type' @@ -5501,7 +5532,6 @@ paths: - homepage - cartpage text: Some text - x-codegen-request-body-name: body delete: tags: - Checkout Consignments @@ -7025,7 +7055,6 @@ paths: AllowDynamicQueryParameters: false AllowDynamicFormParameters: false IsMultiContentStreaming: false - x-codegen-request-body-name: body '/checkouts/{checkoutId}/coupons/{couponCode}': delete: tags: @@ -7794,11 +7823,16 @@ paths: examples: example-1: value: - '0': null - '592': null maxUses: 1 ttl: 2 description: Use the checkout token to display a confirmation page for a guest shopper. + + **Usage Notes** + * The response from performing this POST request is a checkout token. + * The checkout token is a single-use token that is not order-dependent. You cannot create this token after finalizing an order. + * After completing the order, you can redirect the shopper to /order-confirmation/{orderId}?t={checkoutToken}. + * After token validation, the /order-confirmation/{orderId} page displays. + * The `ORDER_TOKEN` should match the order or the logged-in customer can access the order. components: schemas: Checkout: @@ -8666,10 +8700,12 @@ components: properties: field_id: type: string - description: '' + description: 'You must provide the form field ID value as the `field_id`.' field_value: - type: string + type: string description: 'This can also be an array for fields that need to support a list of values (e.g., a set of check boxes.)' + required: + - field_id line_items: type: array description: '' @@ -8689,6 +8725,7 @@ components: format: int32 pickup_option: type: object + description: 'Assigns a pickup consignment. Note: You cannot assign a shipping method with a pickup consignment.' properties: pickup_method_id: type: integer @@ -8696,10 +8733,8 @@ components: x-internal: false UpdateConsignmentRequest: title: Update Consignment Request - type: array - items: - type: object - properties: + type: object + properties: address: title: Address Properties required: @@ -9692,14 +9727,14 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header diff --git a/reference/consent.sf.yml b/reference/consent.sf.yml index 010aa62dc..a026f8030 100644 --- a/reference/consent.sf.yml +++ b/reference/consent.sf.yml @@ -10,9 +10,9 @@ info: description: |- Specify shopper cookie consent preferences. - For info about API accounts, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). + For info about API accounts, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). - For info about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#same-origin-cors-authentication). + For info about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#same-origin-cors-authentication). version: Storefront tags: - name: Consent @@ -73,7 +73,7 @@ components: 3 - Analytics 4 - Targeting; Advertising - For further definition of these categories, see [Scripts API](/api-docs/store-management/scripts). + For further definition of these categories, see [Scripts API](/docs/integrations/scripts). properties: allow: type: array diff --git a/reference/currencies.v2.yml b/reference/currencies.v2.yml index 740ec4b3b..83063f2bf 100644 --- a/reference/currencies.v2.yml +++ b/reference/currencies.v2.yml @@ -10,13 +10,13 @@ info: | -- | -- | | Default Currency | Storeʼs default currency is the one from which any auto-conversion of pricing (product, tax, shipping, promotions) will happen.| | Display Currency | Currency that is displayed on the storefront. This might or might not mean that shopper can actually transact in that currency. Display currency is also often called "presentment currency" in the payments industry. | - | Transactional Currency | Transactional currency is what currency and amount BC passes to the payment provider and the currency/amount that the shopper will be charged to their bank account. If thereʼs a discrepancy between the storefront display currency and the transactional currency, a shopper has to pay a conversion fee and the conversion rate that will be used will be outside of BCʼs purview. | - | Settlement Currency | This is the currency in which the merchant gets paid out to their bank account. If thereʼs a discrepancy between the currency that shopper transacts in and the currency in which merchant settles, merchant has to pay a conversion fee and the conversion rate used will be outside of BCʼs purview. Merchant is able to set their settlement currency through their payment provider. | + | Transactional Currency | Transactional currency is what currency and amount BigCommerce passes to the payment provider and the currency/amount that the shopper will be charged to their bank account. If thereʼs a discrepancy between the storefront display currency and the transactional currency, a shopper has to pay a conversion fee and the conversion rate that will be used will be outside of BigCommerceʼs purview. | + | Settlement Currency | This is the currency in which the merchant gets paid out to their bank account. If thereʼs a discrepancy between the currency that shopper transacts in and the currency in which merchant settles, merchant has to pay a conversion fee and the conversion rate used will be outside of BigCommerceʼs purview. Merchant is able to set their settlement currency through their payment provider. | |BigCommerce Conversion Rate | Any conversion rate set on BigCommerce used to convert product’s default currency pricing into a new non-default currency. Conversion rate could be static or dynamic. | | Static Conversion Rate | One of the two auto-converted pricing options. If a merchant manually enters a static conversion rate, then the conversion rate will remain the same until/unless merchant updates their currency settings to use a different conversion rate. The advantage of using this method is to avoid constantly fluctuating price in non-default currencies. | | Dynamic Conversion Rate | One of the two auto-converted pricing options. If a merchant selects a dynamic conversion rate, theyʼve tied themselves to a currency conversion service, which will update the conversion rate at a certain frequency. This helps shopper-facing pricing remain most aligned to the storeʼs default currency and keeps non-default currency conversion rate at market rate. Merchant can either use BigCommerce Currency Service provided in the Currency setup page, or they can use API to automatically update the exchange rate from their trusted source. | - | Bank Conversion Rate | Conversion rate used by merchant’s or shopper’s payment or credit card provider when auto-converting from store’s transactional currency. This rate might not align to the BC conversion rate and BC has no visibility into it. | - | Multi Currency Pricing | Rather than opting for auto-converting product pricing from default currency using BC conversion rate, merchant has a choice to set price per product per currency. This will be implemented through price lists. | + | Bank Conversion Rate | Conversion rate used by merchant’s or shopper’s payment or credit card provider when auto-converting from store’s transactional currency. This rate might not align with the BigCommerce conversion rate and BigCommerce has no visibility into it. | + | Multi Currency Pricing | Rather than opting for auto-converting product pricing from default currency using BigCommerce conversion rate, merchant has a choice to set price per product per currency. This will be implemented through price lists. | ## FAQ @@ -26,11 +26,11 @@ info: ## Resources - - [How Currencies Work](/api-docs/catalog/currencies/how-currencies-work) - - [Price List API](/docs/rest-management/price-lists) - - [Using Price Lists](https://support.bigcommerce.com/s/article/Price-Lists) (BigCommerce Knowledge Base) - - [Managing Currencies](https://support.bigcommerce.com/s/article/Managing-Currencies-Beta) (BigCommerce Knowledge Base) - - [Tax](https://support.bigcommerce.com/s/article/Manual-Tax-Setup#intro1) (BigCommerce Knowledge Base) + - [How Currencies Work](/docs/store-operations/currencies/guide) + - [Price List API Reference](/docs/rest-management/price-lists) + - [Using Price Lists (Help Center)](https://support.bigcommerce.com/s/article/Price-Lists) + - [Managing Currencies (Help Center)](https://support.bigcommerce.com/s/article/Managing-Currencies-Beta) + - [Tax (Help Center)](https://support.bigcommerce.com/s/article/Manual-Tax-Setup#intro1) version: '' termsOfService: 'https://www.bigcommerce.com/terms' contact: @@ -52,7 +52,6 @@ tags: paths: /currencies: parameters: - - $ref: '#/components/parameters/Accept' get: tags: @@ -60,6 +59,23 @@ paths: summary: Get All Currencies description: Returns a list of all store *Currency*. operationId: getAllCurrencies + parameters: + - name: page + description: | + Specifies the page number in a limited (paginated) list of currencies. + required: false + in: query + schema: + type: integer + default: 1 + - name: limit + description: | + Controls the number of items per page in a limited (paginated) list of currencies. + required: false + in: query + schema: + type: integer + default: 50 responses: '200': description: "" @@ -94,7 +110,7 @@ paths: * date_modified - The `is_default` property can only be set to true. The value of `is_default` cannot be unset, only overridden. To change the storeʼs default currency in the BigCommerce control panel, please see [Managing Currencies](https://support.bigcommerce.com/articles/Public/Managing-Currencies/?q=currency&l=en_US&fs=Search&pn=1#default). + The `is_default` property can only be set to true. The value of `is_default` cannot be unset, only overridden. To change the storeʼs default currency in the BigCommerce control panel, please see [Managing Currencies (Help Center)](https://support.bigcommerce.com/s/article/Managing-Currencies-Beta). parameters: - $ref: '#/components/parameters/ContentType' requestBody: @@ -125,7 +141,6 @@ paths: type: object /currencies/{id}: parameters: - - $ref: '#/components/parameters/Accept' - name: id in: path @@ -202,14 +217,14 @@ components: currency_Base: title: currency_Base required: - - currency_code - - currency_exchange_rate - - decimal_places - - decimal_token - - name - - thousands_token - - token - - token_location + - currency_code + - currency_exchange_rate + - decimal_places + - decimal_token + - name + - thousands_token + - token + - token_location type: object properties: is_default: @@ -375,14 +390,14 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header diff --git a/reference/current_customer.yml b/reference/current_customer.yml index 4f36e79be..a91f0fe60 100644 --- a/reference/current_customer.yml +++ b/reference/current_customer.yml @@ -4,11 +4,11 @@ info: description: |- Identify logged-in customers securely via JavaScript. - [Learn more about the current customer API](/api-docs/customers/current-customer-api). + [Learn more about the current customer API](/docs/start/authentication/current-customer). - For info about API accounts, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). + For info about API accounts, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). - For info about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#client-id). + For info about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#client-id). > #### Note > * Substitute your storefront domain for `yourstore.example.com`. diff --git a/reference/custom-template-associations.v3.yml b/reference/custom-template-associations.v3.yml index 1f6970c96..96c1d33ea 100644 --- a/reference/custom-template-associations.v3.yml +++ b/reference/custom-template-associations.v3.yml @@ -3,7 +3,7 @@ info: title: Custom Template Associations version: '' description: |- - Efficiently associate a stencil themeʼs custom templates to products, categories, brands, and pages. + Efficiently associate a Stencil themeʼs custom templates to products, categories, brands, and pages. ## Creating template associations @@ -30,7 +30,7 @@ info: ## Getting entity IDs - Use the [Catalog API](/docs/rest-management/catalog) to get the `entity_id` for `category`, `product`, and `brand` entity types. For example, to [get all products](/docs/rest-management/catalog/products#get-all-products), send a `GET` request to `/v3/catalog/products`. + Use the [Catalog API](/docs/rest-catalog/products) to get the `entity_id` for `category`, `product`, and `brand` entity types. For example, to [get all products](/docs/rest-catalog/products#get-all-products), send a `GET` request to `/v3/catalog/products`. ```http GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/catalog/products @@ -109,7 +109,7 @@ info: * [Get Channel Active Theme](/docs/rest-management/channels/channel-active-theme#get-a-channel-active-theme) * [Get Available Custom Templates](/docs/rest-content/themes/theme-custom-templates#get-custom-templates) - * [Catalog API](/docs/rest-management/catalog) + * [Catalog API](/docs/rest-catalog) * [Pages API](/docs/rest-content/pages) * [Channels API](/docs/rest-management/channels) termsOfService: 'https://www.bigcommerce.com/terms' @@ -477,14 +477,14 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header diff --git a/reference/customer_login.yml b/reference/customer_login.yml index de2d3cc73..e147e457b 100644 --- a/reference/customer_login.yml +++ b/reference/customer_login.yml @@ -4,11 +4,11 @@ info: description: |- Enable single sign-on for shoppers on BigCommerce hosted storefronts. - [Learn more about the customer login API](/api-docs/customers/customer-login-api). + [Learn more about the customer login API](/docs/start/authentication/customer-login). - For info about API accounts, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). + For info about API accounts, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). - For info about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#user-generated-jwts). + For info about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#user-generated-jwts). termsOfService: 'https://www.bigcommerce.com/terms' contact: name: BigCommerce @@ -32,7 +32,7 @@ paths: description: |- The customer login access point URL. - [Learn more about the Customer Login API](/api-docs/customers/customer-login-api). + [Learn more about the Customer Login API](/docs/start/authentication/customer-login). ## Example diff --git a/reference/customers.sf.yml b/reference/customers.sf.yml index f27d2ec65..a4b53ddf2 100644 --- a/reference/customers.sf.yml +++ b/reference/customers.sf.yml @@ -3,11 +3,11 @@ info: version: Storefront title: Storefront Customers description: |- - Manage customers and data via front-end JavaScript on BigCommerce stencil powered storefronts. + Manage customers and data via front-end JavaScript on BigCommerce Stencil-powered storefronts. - For info about API accounts, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). + For info about API accounts, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). - For info about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#same-origin-cors-authentication). + For info about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#same-origin-cors-authentication). servers: - url: 'https://{store_domain}/api/storefront' variables: @@ -96,8 +96,4 @@ components: - type: number - type: array items: - type: string -x-stoplight: - docs: - includeDownloadLink: false - showModels: false + type: string \ No newline at end of file diff --git a/reference/customers.v2.yml b/reference/customers.v2.yml index baa28dad7..305e48ab2 100644 --- a/reference/customers.v2.yml +++ b/reference/customers.v2.yml @@ -2,31 +2,32 @@ openapi: '3.0.1' info: title: Customers V2 description: |- - Create and Manage Customers, Customer Addresses, and Customer Groups. Additionally, validate customer passwords. To learn more about Customers see [here](/api-docs/customers/customers-subscribers-overview). + Create and Manage Customers, Customer Addresses, and Customer Groups. Additionally, validate customer passwords. To learn more about Customers see [here](/docs/store-operations/customers/customers-subscribers-overview). ## Available Endpoints | Resource / Endpoint | Description | - |-----------------------------------------|-------------------------------------------------------------------------------| + |:----------------------------------------|:------------------------------------------------------------------------------| | Customers | Identity and account details for customers shopping on BigCommerce stores | - | Customers Addresses | Postal address belonging to a customer. | + | Customers Addresses | Postal address belonging to a customer | | Customers Groups | Groupings of customers who share the same level of access and discounts | | Customers Validate Password | Validate customer passwords | ## Usage Notes **Customer Groups** * Customer Groups are only available on specific plans. + **Customers vs. Subscribers** * A subscriber is not always a customer. Someone can sign up for the newsletter only and not create an account. * A customer is not always a subscriber. Signing up for the newsletter is a separate action from creating an account and purchasing an item. * A customer and a subscriber can be the same. If a shopper checks out on the storefront, creates an account and opts into the newsletter, they are a customer and a subscriber. ## Resources ### Related APIs / Endpoints - [Customer Login API](/api-docs/customers/customer-login-api) - - [Current Customer API](/api-docs/customers/current-customer-api) + - [Customer Login API](/docs/start/authentication/customer-login) + - [Current Customer API](/docs/start/authentication/current-customer) - [Customers API (v3)](/docs/rest-management/customers) - [Subscribers API](/docs/rest-management/subscribers) ### Webhooks - - [Customers](/api-docs/store-management/webhooks/webhook-events#customer) + - [Customers](/docs/integrations/webhooks/events#customer) termsOfService: 'https://www.bigcommerce.com/terms' contact: name: BigCommerce @@ -55,7 +56,7 @@ paths: tags: - Customers summary: Get All Customers - description: 'Returns a list of all *Customers*. Default sorting is by customer id, from lowest to highest. Optional parameters can be passed in.' + description: Returns a list of all *Customers*. Default sorting is by `customer_ID`, from lowest to highest. Optional parameters can be passed in. operationId: getAllCustomers parameters: - name: first_name @@ -165,12 +166,13 @@ paths: ``` ## Forcing Password Resets To force a customer to reset their password upon their next login attempt, give the `force_reset` field a value of true, as shown here: - ```json + ```js showLineNumbers copy { "_authentication": { "force_reset": true } } + ``` operationId: createANewCustomer parameters: - $ref: '#/components/parameters/ContentType' @@ -183,7 +185,7 @@ paths: _authentication: type: object properties: {} - description: 'This can vary depending on the action being taken to update, validate or force a password change. See Update Customer' + description: This can vary depending on the action being taken to update, validate or force a password change. See [Customers V2, Update a customer (Deprecated)](/docs/rest-management/customers-v2#update-a-customer). company: type: string first_name: @@ -217,7 +219,7 @@ paths: tags: - Customers summary: Delete Customers - description: 'By default, it deletes all *Customers*. Up to 100 customers per batch can be deleted. ' + description: By default, it deletes all *Customers*. Up to 100 customers per batch can be deleted. operationId: deleteAllCustomers responses: '204': @@ -273,6 +275,7 @@ paths: summary: Update a Customer description: |- Updates a *Customer*. + **Read Only Fields** * id * date_created @@ -280,21 +283,25 @@ paths: * accepts_marketing * addresses * form_fields + ## Notes The `_authentication` object exposes functionality associated with the customer’s ability to log in to the store. All properties of the `_authentication` object are optional. When the `_authentication` object is not supplied with an update request, then the existing customer password remains the same. ## Updating Passwords To manually update a customer password in the same way as the control panel, supply a value for the `password` field: - ``` + + ```js showLineNumbers copy { "_authentication": { "password": "12w69Y217PYR96J" } } + ``` + #### Confirming Passwords An additional optional `password_confirmation` field can also be sent, providing password confirmation as a service: - ``` + ```js showLineNumbers copy { "_authentication": { "password": "12w69Y217PYR96J" @@ -304,7 +311,7 @@ paths: ``` #### Forcing Password Resets To force a customer to reset their password upon their next login attempt, give the `force_reset` field a value of true, as shown here: - ``` + ```js showLineNumbers copy { "_authentication": { "force_reset": true @@ -318,108 +325,7 @@ paths: content: application/json: schema: - title: Customers - required: - - email - - first_name - - last_name - type: object - properties: - id: - type: integer - description: Unique numeric ID of this customer. This is a READ-ONLY field; do not set or modify its value in a POST or PUT request. - example: 1 - _authentication: - type: object - properties: - force_reset: - type: boolean - password: - type: string - password_confirmation: - type: string - description: 'Not returned in any responses, but accepts up to two fields allowing you to set the customer’s password. If a password is not supplied, it is generated automatically. For further information about using this object, please see the Customers resource documentation.' - company: - type: string - description: The name of the company for which the customer works. - example: BigCommerce - first_name: - type: string - description: First name of the customer. - example: Jane - last_name: - type: string - description: Last name of the customer. - example: Doe - email: - type: string - description: Email address of the customer. - example: janedoe@example.com - phone: - type: string - description: Phone number of the customer. - example: '1234567890' - date_created: - type: string - description: Date on which the customer registered from the storefront or was created in the control panel. This is a READ-ONLY field; do not set or modify its value in a POST or PUT request. - date_modified: - type: string - description: | - Date on which the customer updated their details in the storefront or was updated in the control panel. This is a READ-ONLY field; do not set or modify its value in a POST or PUT request. - store_credit: - type: string - description: 'The amount of credit the customer has. (Float, Float as String, Integer)' - example: '0' - registration_ip_address: - type: string - description: The customer’s IP address when they signed up. - example: 12.345.678.910 - customer_group_id: - type: integer - description: The group to which the customer belongs. - example: 2 - notes: - type: string - description: Store-owner notes on the customer. - tax_exempt_category: - type: string - description: 'If applicable, the tax-exempt category of the shopper’s customer account. You can apply a tax-exempt category to multiple customers. This code should match the exemption codes provided by the third-party integration. ' - accepts_marketing: - type: boolean - description: 'If the customer accepts product review emails or abandon cart emails. Read-Only. ' - readOnly: true - example: true - addresses: - title: Address Field Resource - type: object - properties: - url: - type: string - description: Full URL of where the resource is located. - example: 'https://api.bigcommerce.com/stores/{store_hash}/v2/customers/5/addresses' - resource: - type: string - description: Resource being accessed. - example: /customers/5/addresses - form_fields: - type: array - description: Array of custom fields. This is a READ-ONLY field; do not set or modify its value in a POST or PUT request. - items: - title: Form Fields - type: object - properties: - name: - type: string - description: Name of the form field - example: License Id - value: - type: string - description: Value of the form field - example: 123BAF - reset_pass_on_login: - type: boolean - description: Force a password change on next login. - example: false + $ref: '#/components/schemas/customer_Put' required: false responses: '200': @@ -448,7 +354,7 @@ paths: tags: - Customers summary: Get a Count of Customers - description: 'Returns a count of all *Customers*. ' + description: Returns a count of all *Customers*. operationId: getACountOfCustomers responses: '200': @@ -497,16 +403,16 @@ paths: description: |- **This endpoint has special rate limiting protections to protect against abuse.** - Provided a password, will return a true/false response indicating if the provided password matches the customer’s current password. This endpoint is useful if you want to power the login of another system using BigCommerce’s stored customer accounts, or as a safe way to migrate passwords to another system (by checking them against BigCommerce’s password, and if correct, storing it in another system securely.)If the password matches what’s stored against the customer account, the response will be: + Provided a password, will return a true/false response indicating if the provided password matches the customer’s current password. This endpoint is useful if you want to power the login of another system using BigCommerce’s stored customer accounts, or as a safe way to migrate passwords to another system (by checking them against BigCommerce’s password, and if correct, storing it in another system securely.) If the password matches what’s stored against the customer account, the response will be: - ```json + ```js showLineNumbers copy { "success": "true" } ``` If the password does NOT match, the response will instead be: - ```json + ```js showLineNumbers copy { "success": "false" } @@ -550,14 +456,14 @@ paths: parameters: - name: page in: query - description: Number of pages + description: Number of pages. schema: exclusiveMaximum: false exclusiveMinimum: false type: number - name: limit in: query - description: Count per page + description: Count per page. schema: exclusiveMaximum: false exclusiveMinimum: false @@ -618,14 +524,14 @@ paths: parameters: - name: page in: query - description: Number of pages + description: Number of pages. schema: exclusiveMaximum: false exclusiveMinimum: false type: number - name: limit in: query - description: Count per page + description: Count per page. schema: exclusiveMaximum: false exclusiveMinimum: false @@ -649,14 +555,14 @@ paths: parameters: - name: page in: query - description: Number of pages + description: Number of pages. schema: exclusiveMaximum: false exclusiveMinimum: false type: number - name: limit in: query - description: Count per page + description: Count per page. schema: exclusiveMaximum: false exclusiveMinimum: false @@ -675,6 +581,7 @@ paths: summary: Update a Customer Address description: |- Updates a *Customer Address*. + **Read Only Fields** * id * country_iso2 @@ -699,8 +606,9 @@ paths: properties: id: type: integer - description: ID of this customer address. READ-ONLY + description: ID of this customer address. Read-Only. example: 3 + readOnly: true customer_id: type: integer description: ID of the associated customer. @@ -719,11 +627,11 @@ paths: example: BigCommerce street_1: type: string - description: 'The customer’s street address, line 1.' + description: The customer’s street address, line 1. example: 123 Main Street street_2: type: string - description: 'The customer’s street address, line 2.' + description: The customer’s street address, line 2. city: type: string description: The customer’s city/town/suburb. @@ -742,8 +650,9 @@ paths: example: United States country_iso2: type: string - description: 2-letter ISO Alpha-2 code for the customer’s country. READ-ONLY + description: 2-letter ISO Alpha-2 code for the customer’s country. Read-Only. example: US + readOnly: true phone: type: string description: The customer’s phone number. @@ -803,14 +712,14 @@ paths: parameters: - name: page in: query - description: Number of pages + description: Number of pages. schema: exclusiveMaximum: false exclusiveMinimum: false type: number - name: limit in: query - description: Count per page + description: Count per page. schema: exclusiveMaximum: false exclusiveMinimum: false @@ -832,36 +741,80 @@ paths: tags: - Customer Groups summary: Get All Customer Groups - description: 'Returns a list of *Customer Groups*. Default sorting is by customer-group id, from lowest to highest.' + description: |- + Returns a list of *Customer Groups*. Default sorting is by customer-group ID, from lowest to highest. + + **Note:** + The default rate limit for this endpoint is 40 concurrent requests. operationId: getAllCustomerGroups parameters: - name: page in: query - description: Number of pages + description: Number of pages. schema: exclusiveMaximum: false exclusiveMinimum: false type: number - name: limit in: query - description: Count per page + description: Count per page. schema: exclusiveMaximum: false exclusiveMinimum: false type: number - name: name in: query - description: 'Filter customer groups by exact name match. Can use `name:like` to filter using a fuzzy matching method. This is good for implementing search.' + description: Filter customer groups by exact name match. schema: type: string + - name: 'name:like' + in: query + description: Filter customer groups by name, using a fuzzy matching method. + schema: + type: string - name: is_default in: query - description: Whether customers who sign up are added to this group by default. + description: Filter by customers who sign up are added to this group by default. schema: type: boolean + - name: date_created + in: query + description: Filter customer groups by date_created. `date_created=2018-09-05T13:43:54` + schema: + type: string + format: date-time + - name: 'date_created:max' + in: query + description: Filter customer groups by maximum date_created. `date_created:max=2018-09-10` + schema: + type: string + - name: 'date_created:min' + in: query + description: Filter customer groups by date_created. `date_created:min=2018-09-05` + schema: + type: string + format: date-time + - name: date_modified + in: query + description: Filter customer groups by date_modified. `date_modified=2018-09-05T13:45:03` + schema: + type: string + format: date-time + - name: '`date_modified:min`' + in: query + description: Filter customer groups by minimum date_modified. `date_modified:min=2019-09-04T:00:00:00` or `date_modified:min=2019-09-04` + schema: + type: string + format: date-time + - name: '`date_modified:max`' + in: query + description: Filter customer groups by maximum date_modified. `date_modified:max=2018-09-05T13:45:03` or `date_modified:max=2019-09-04` + schema: + type: string + format: date-time - name: is_group_for_guests in: query - description: If the groups is for guests. There can only be one customer group for guests at a time. + description: Filter whether the group is for guests. There can only be one customer group for guests at a time. schema: type: boolean responses: @@ -879,8 +832,12 @@ paths: summary: Create a Customer Group description: |- Creates a *Customer Group*. + **Required Fields** * name + + **Note:** + The default rate limit for this endpoint is 40 concurrent requests. operationId: createACustomerGroup parameters: - $ref: '#/components/parameters/ContentType' @@ -898,7 +855,7 @@ paths: schema: $ref: '#/components/schemas/customerGroup_Full' '207': - description: 'The customer group was created, but the sitewide discount update failed. You may retry the request.' + description: The customer group was created, but the sitewide discount update failed. You may retry the request. content: application/json: schema: @@ -935,23 +892,57 @@ paths: parameters: - name: page in: query - description: Number of pages + description: Number of pages. schema: exclusiveMaximum: false exclusiveMinimum: false type: number - name: limit in: query - description: Count per page + description: Count per page. schema: exclusiveMaximum: false exclusiveMinimum: false type: number - name: name in: query - description: Name of the customer groups + description: Name of the customer groups. + schema: + type: string + - name: date_created + in: query + description: 'Filter items by date_created. `date_created=2018-09-05T13:43:54`' schema: type: string + format: date-time + - name: 'date_created:max' + in: query + description: 'Filter items by maximum date_created. `date_created:max=2018-09-10`' + schema: + type: string + - name: 'date_created:min' + in: query + description: 'Filter items by date_created. `date_created:min=2018-09-05`' + schema: + type: string + format: date-time + - name: date_modified + in: query + description: 'Filter items by date_modified. `date_modified=2018-09-05T13:45:03`' + schema: + type: string + format: date-time + - name: 'date_modified:min' + in: query + description: 'Filter items by minimum date_modified. `date_modified:min=2019-09-04T:00:00:00` or `date_modified:min=2019-09-04`' + schema: + type: string + - name: 'date_modified:max' + in: query + description: 'Filter items by maximum date_modified. `date_modified:max=2018-09-05T13:45:03` or `date_modified:max=2019-09-04`' + schema: + type: string + format: date-time - name: is_default in: query description: Whether customers who sign up are added to this group by default. @@ -959,11 +950,18 @@ paths: type: boolean responses: '200': - description: '' + description: The request was successful. content: application/json: schema: $ref: '#/components/schemas/customerGroup_Full' + '400': + description: |- + Bad Request. The requested resource could not be downloaded and may be invalid. Possible reasons include malformed request syntax or the file host blocking requests. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorRequest' put: tags: - Customer Groups @@ -991,7 +989,7 @@ paths: schema: $ref: '#/components/schemas/customerGroup_Full' '207': - description: 'The customer group was updated, but the sitewide discount update failed. You may retry the request.' + description: The customer group was updated, but the sitewide discount update failed. You may retry the request. content: application/json: schema: @@ -1013,13 +1011,22 @@ paths: summary: Delete a Customer Group description: |- Deletes a *Customer Group*. + **Notes** - All existing customers are unassigned from the group when it is deleted. + - All existing customers are unassigned from the group when it is deleted. + - The default rate limit for this endpoint is 40 concurrent requests. operationId: deleteACustomerGroup responses: '204': - description: '' + description: No content. Request was successful but produced no response. content: {} + '400': + description: |- + Bad Request. The requested resource could not be downloaded and may be invalid. Possible reasons include malformed request syntax or the file host blocking requests. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorRequest' '/customer_groups/count': parameters: - $ref: '#/components/parameters/Accept' @@ -1027,7 +1034,7 @@ paths: tags: - Customer Groups summary: Get a Count of Customer Groups - description: 'Returns a count of all *Customer Groups*. ' + description: Returns a count of all *Customer Groups*. operationId: getACountOfCustomerGroups responses: '200': @@ -1098,11 +1105,11 @@ components: properties: name: type: string - description: Name of the form field - example: License Id + description: Name of the form field. + example: License ID value: type: string - description: Value of the form field + description: Value of the form field. example: 123BAF x-internal: false customerFormFields: @@ -1111,11 +1118,11 @@ components: properties: name: type: string - description: Name of the form field - example: License Id + description: Name of the form field. + example: License ID value: type: string - description: Value of the form field + description: Value of the form field. example: 123BAF x-internal: false shippingAddress_Full: @@ -1124,7 +1131,7 @@ components: properties: url: type: string - description: URL of the shipping address for api requests + description: URL of the shipping address for API requests. example: 'https://api.bigcommerce.com/stores/{store_hash}/v2/orders/129/shippingaddresses' resource: type: string @@ -1138,15 +1145,18 @@ components: properties: id: type: integer - description: Unique numeric ID of this customer. This is a READ-ONLY field; do not set or modify its value in a POST or PUT request. + description: Unique numeric ID of this customer. This is a Read-Only field; do not set or modify its value in a POST or PUT request. example: 1 + readOnly: true date_created: type: string - description: Date on which the customer registered from the storefront or was created in the control panel. This is a READ-ONLY field; do not set or modify its value in a POST or PUT request. + description: Date on which the customer registered from the storefront or was created in the control panel. This is a Read-Only field; do not set or modify its value in a POST or PUT request. + readOnly: true date_modified: type: string description: | - Date on which the customer updated their details in the storefront or was updated in the control panel. This is a READ-ONLY field; do not set or modify its value in a POST or PUT request. + Date on which the customer updated their details in the storefront or was updated in the control panel. This is a Read-Only field; do not set or modify its value in a POST or PUT request. + readOnly: true - $ref: '#/components/schemas/customer_Base' x-internal: false x-examples: {} @@ -1193,12 +1203,14 @@ components: properties: id: type: integer - description: ID of this customer address. READ-ONLY + description: ID of this customer address. Read-Only. example: 3 + readOnly: true country_iso2: type: string - description: 2-letter ISO Alpha-2 code for the customer’s country. READ-ONLY + description: 2-letter ISO Alpha-2 code for the customer’s country. Read-Only. example: US + readOnly: true - $ref: '#/components/schemas/customerAddress_Base' x-internal: false customerGroup_Full: @@ -1207,11 +1219,11 @@ components: properties: id: type: integer - description: Id of the customer group - example: 1 + description: ID of the customer group. + example: 1 name: type: string - description: Name of the group + description: Name of the group. example: Wholesale is_default: type: boolean @@ -1221,7 +1233,7 @@ components: $ref: '#/components/schemas/categoryAccessLevel_Full' discount_rules: type: array - description: A collection of discount rules that are automatically applied to customers who are members of the group + description: A collection of discount rules that are automatically applied to customers who are members of the group. items: type: object properties: @@ -1240,16 +1252,24 @@ components: - price amount: type: string - description: A float that specifies the value applied to the price modified - example: '"5.0000" (Float, Float as String, Integer)' + description: A float that specifies the value applied to the price modified. (Float, Float as String, Integer) + example: '"5.0000"' price_list_id: type: integer - description: 'If a customer group is assigned to a price list,`method` and `amount` are not shown. `type` and `price_list_id` are returned.' + description: If a customer group is assigned to a price list,`method` and `amount` are not shown. `type` and `price_list_id` are returned. example: 3 + date_created: + type: string + description: Date on which the customer group was created. + example: 2023-07-17 06:30:41 + date_modified: + type: string + description: Date on which the customer group was last modified. + example: 2023-07-25 01:15:19 is_group_for_guests: type: boolean - description: If the groups is for guests. There can only be one customer group for guests at a time. - description: 'When creating a customer group category discount using the API it defaults to "products in this category and its subcategories". In the [Control Panel](https://support.bigcommerce.com/s/article/Customer-Groups#pricing) this can be changed to either "products in this category only" or "products in this category and its subcategories". There are currently no settings to change this behavior via API.' + description: Describes whether the group is for guests. There can only be one customer group for guests at a time. + description: When creating a customer group category discount using the API it defaults to "products in this category and its subcategories". In the [store control panel](https://support.bigcommerce.com/s/article/Customer-Groups#pricing), this can be changed to either "products in this category only" or "products in this category and its subcategories". There are currently no settings to change this behavior with the API. x-internal: false country_Full: title: country_Full @@ -1257,7 +1277,7 @@ components: properties: id: type: integer - description: Id of the country. + description: ID of the country. example: 13 country: type: string @@ -1332,7 +1352,7 @@ components: properties: name: type: string - description: Name of the group + description: Name of the group. example: Wholesale is_default: type: boolean @@ -1342,7 +1362,7 @@ components: $ref: '#/components/schemas/categoryAccessLevel_Full' discount_rules: type: array - description: A collection of discount rules that are automatically applied to customers who are members of the group + description: A collection of discount rules that are automatically applied to customers who are members of the group. items: type: object properties: @@ -1361,23 +1381,31 @@ components: - price amount: type: string - description: A float that specifies the value applied to the price modified - example: '"5.0000" (Float, Float as String, Integer)' + description: A float that specifies the value applied to the price modified. (Float, Float as String, Integer) + example: '"5.0000"' price_list_id: type: integer - description: 'If a customer group is assigned to a price list,`method` and `amount` are not shown. `type` and `price_list_id` are returned.' + description: If a customer group is assigned to a price list,`method` and `amount` are not shown. `type` and `price_list_id` are returned. example: 3 + date_created: + type: string + description: Date on which the customer group was created. + example: 2023-07-17 06:30:41 + date_modified: + type: string + description: Date on which the customer group was last modified. + example: 2023-07-25 01:15:19 is_group_for_guests: type: boolean - description: If the groups is for guests. There can only be one customer group for guests at a time. - description: 'When creating a customer group category discount using the API it defaults to "products in this category and its subcategories". In the [Control Panel](https://support.bigcommerce.com/s/article/Customer-Groups#pricing) this can be changed to either "products in this category only" or "products in this category and its subcategories". There are currently no settings to change this behavior via API.' + description: Describes whether the group is for guests. There can only be one customer group for guests at a time. + description: When creating a customer group category discount using the API it defaults to "products in this category and its subcategories". In the [store control panel](https://support.bigcommerce.com/s/article/Customer-Groups#pricing), this can be changed to either "products in this category only" or "products in this category and its subcategories". There are currently no settings to change this behavior with the API. x-internal: false validatePassword: type: object properties: success: type: boolean - description: Will return `true` or `false` + description: Will return `true` or `false`. x-internal: false customer_Base: title: customer_Base @@ -1386,7 +1414,7 @@ components: properties: _authentication: type: object - description: 'Not returned in any responses, but accepts up to two fields allowing you to set the customer’s password. If a password is not supplied, it is generated automatically. For further information about using this object, please see the Customers resource documentation.' + description: Not returned in any responses, but accepts up to two fields allowing you to set the customer’s password. If a password is not supplied, it is generated automatically. For further information about using this object, please see the Customers resource documentation. properties: force_reset: type: boolean @@ -1416,7 +1444,7 @@ components: example: '1234567890' store_credit: type: string - description: 'The amount of credit the customer has. (Float, Float as String, Integer)' + description: The amount of credit the customer has. (Float, Float as String, Integer) example: '0' registration_ip_address: type: string @@ -1429,12 +1457,13 @@ components: notes: type: string description: Store-owner notes on the customer. + tax_exempt_category: type: string - description: 'If applicable, the tax-exempt category of the shopper’s customer account. You can apply a tax-exempt category to multiple customers. This code should match the exemption codes provided by the third-party integration.' + description: If applicable, the tax-exempt category of the shopper’s customer account. You can apply a tax-exempt category to multiple customers. This code should match the exemption codes provided by the third-party integration. accepts_marketing: type: boolean - description: 'If the customer accepts product review emails or abandon cart emails. Read-Only. ' + description: Describes whether the customer accepts product review emails or abandon cart emails. Read-Only. example: true readOnly: true addresses: @@ -1451,19 +1480,20 @@ components: example: /customers/5/addresses form_fields: type: array - description: Array of custom fields. This is a READ-ONLY field; do not set or modify its value in a POST or PUT request. + description: Array of custom fields. This is a Read-Only field; do not set or modify its value in a POST or PUT request. nullable: true + readOnly: true items: title: Form Fields type: object properties: name: type: string - description: Name of the form field - example: License Id + description: Name of the form field. + example: License ID value: type: string - description: Value of the form field + description: Value of the form field. nullable: true reset_pass_on_login: type: boolean @@ -1473,6 +1503,131 @@ components: - first_name - last_name - email + customer_Put: + title: customer_Put + type: object + properties: + id: + type: integer + description: Unique numeric ID of this customer. This is a Read-Only field; do not set or modify its value in a POST or PUT request. + example: 1 + readOnly: true + _authentication: + type: object + properties: + force_reset: + type: boolean + password: + type: string + password_confirmation: + type: string + description: Not returned in any responses, but accepts up to two fields allowing you to set the customer’s password. If a password is not supplied, it is generated automatically. For further information about using this object, please see the Customers resource documentation. + company: + type: string + description: The name of the company for which the customer works. + example: BigCommerce + first_name: + type: string + description: First name of the customer. + example: Jane + last_name: + type: string + description: Last name of the customer. + example: Doe + email: + type: string + description: Email address of the customer. + example: janedoe@example.com + phone: + type: string + description: Phone number of the customer. + example: '1234567890' + date_created: + type: string + description: Date on which the customer registered from the storefront or was created in the control panel. This is a Read-Only field; do not set or modify its value in a POST or PUT request. + readOnly: true + date_modified: + type: string + description: |- + Date on which the customer updated their details in the storefront or was updated in the control panel. This is a READ-ONLY field; do not set or modify its value in a POST or PUT request. + readOnly: true + store_credit: + type: string + description: The amount of credit the customer has. (Float, Float as String, Integer) + example: '0' + registration_ip_address: + type: string + description: The customer’s IP address when they signed up. + example: 12.345.678.910 + customer_group_id: + type: integer + description: The group to which the customer belongs. + example: 2 + notes: + type: string + description: Store-owner notes on the customer. + tax_exempt_category: + type: string + description: If applicable, the tax-exempt category of the shopper’s customer account. You can apply a tax-exempt category to multiple customers. This code should match the exemption codes provided by the third-party integration. + accepts_marketing: + type: boolean + description: Describes whether the customer accepts product review emails and abandon cart emails. Read-Only. + readOnly: true + example: true + addresses: + title: Address Field Resource + type: object + properties: + url: + type: string + description: Full URL of where the resource is located. + example: 'https://api.bigcommerce.com/stores/{store_hash}/v2/customers/5/addresses' + resource: + type: string + description: Resource being accessed. + example: /customers/5/addresses + form_fields: + type: array + description: Array of custom fields. This is a Read-Only field; do not set or modify its value in a POST or PUT request. + readOnly: true + items: + title: Form Fields + type: object + properties: + name: + type: string + description: Name of the form field. + example: License ID + value: + type: string + description: Value of the form field. + example: 123BAF + reset_pass_on_login: + type: boolean + description: Force a password change on next login. + example: false + ErrorRequest: + type: object + properties: + errors: + type: array + items: + $ref: '#/components/schemas/ErrorBasic' + ErrorBasic: + type: object + properties: + status: + description: | + The HTTP status code. + type: integer + title: + description: | + The error title describing the particular error. + type: string + type: + type: string + x-tags: + - Models customerAddress_Base: title: customerAddress_Base required: @@ -1582,7 +1737,7 @@ components: is_group_for_guests: name: is_group_for_guests in: query - description: If the groups is for guests. There can only be one customer group for guests at a time. + description: Describes whether the group is for guests. There can only be one customer group for guests at a time. schema: type: boolean securitySchemes: @@ -1600,15 +1755,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header diff --git a/reference/customers.v3.yml b/reference/customers.v3.yml index 002557f95..7362cdd31 100644 --- a/reference/customers.v3.yml +++ b/reference/customers.v3.yml @@ -6,7 +6,7 @@ info: Create and manage customers. ## Resources - * [Customer and Subscribers Overview](/api-docs/store-management/customers). + * [Customer and Subscribers Overview](/docs/store-operations/customers/customers-subscribers-overview). termsOfService: 'https://www.bigcommerce.com/terms' contact: name: BigCommerce @@ -171,13 +171,18 @@ paths: * `segment_ids`- segments the customer belongs to (Beta) `include=addresses,storecredit,attributes,formfields,shopper_profile_id,segment_ids` + explode: false schema: - type: string - enum: - - addresses - - storecredit - - attributes - - formfields + type: array + items: + type: string + enum: + - addresses + - storecredit + - attributes + - formfields + - shopper_profile_id + - segment_ids - in: query name: sort description: 'Sort items by date_created, date_modified, or last_name:* `date_created:asc` - date created, ascending* `date_created:desc` - date created, descending* `last_name:asc` - last name, ascending* `last_name:desc` - last name, descending * `date_modified:asc` - date modified, ascending* `date_modified:desc`- date modified, descending Example: `sort=last_name:asc`' @@ -213,9 +218,6 @@ paths: * Attributes must be [created](/docs/rest-management/customers/customer-attributes#create-a-customer-attribute) **BEFORE** creating a customer. * attribute_id * attribute_value -- This is input as a string, regardless of the [Type](/docs/rest-management/customers/customer-attributes#create-a-customer-attribute). - - **Limits** - * Limit of 10 concurrent requests **Notes** @@ -347,22 +349,11 @@ paths: last_name: string company: string phone: string + registration_ip_address: string notes: string tax_exempt_category: string customer_group_id: 0 id: 1 - addresses: - - address1: string - address2: string - address_type: string - city: string - company: string - country_code: string - first_name: string - last_name: string - phone: string - postal_code: string - state_or_province: string authentication: force_password_reset: true new_password: string123 @@ -520,6 +511,7 @@ paths: * **state_or_province** * **postal_code** * An attempt to create an address that already exists will result in no change to the address or custom form field values, an HTTP 200 return code, and the address will be absent from the response body. + * The default rate limit for this endpoint is 10 concurrent requests. summary: Create a Customer Address operationId: CustomersAddressesPost deprecated: false @@ -1483,8 +1475,6 @@ paths: - Customer Consent operationId: CustomersConsentByCustomerId_GET deprecated: false - parameters: - - $ref: '#/components/parameters/customerId' responses: '200': $ref: '#/components/responses/consent_Resp' @@ -1521,7 +1511,6 @@ paths: schema: type: string default: application/json - - $ref: '#/components/parameters/customerId' requestBody: content: application/json: @@ -1554,11 +1543,7 @@ paths: schema: $ref: '#/components/schemas/ErrorResponse' parameters: - - schema: - type: string - name: customerId - in: path - required: true + - $ref: '#/components/parameters/customerId' '/customers/{customerId}/stored-instruments': get: summary: Get Stored Instruments @@ -2508,15 +2493,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header schemas: diff --git a/reference/email_templates.v3.yml b/reference/email_templates.v3.yml index a1d216c8a..95b83b424 100644 --- a/reference/email_templates.v3.yml +++ b/reference/email_templates.v3.yml @@ -341,15 +341,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header diff --git a/reference/form_fields.sf.yml b/reference/form_fields.sf.yml index 674a97cbb..b0eef355b 100644 --- a/reference/form_fields.sf.yml +++ b/reference/form_fields.sf.yml @@ -4,9 +4,9 @@ info: description: |- Read form fields on a BigCommerce hosted storefront. - For info about API accounts, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). + For info about API accounts, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). - For info about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#same-origin-cors-authentication). + For info about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#same-origin-cors-authentication). > #### Warning > Breaking changes may be introduced to this endpoint while in beta. @@ -79,13 +79,13 @@ components: description: Field name custom: type: boolean - description: Wether is a custom field or system built-in field. + description: Whether this is a custom field or system built-in field. label: type: string description: User-friendly label required: type: boolean - description: Wether this field is required or not + description: Whether this field is required or not default: type: string description: The field unique ID diff --git a/reference/geography.v2.yml b/reference/geography.v2.yml index 1368d091e..3214a4e7e 100644 --- a/reference/geography.v2.yml +++ b/reference/geography.v2.yml @@ -8,6 +8,7 @@ info: paths: '/countries': get: + operationId: get-all-countries description: 'Get a list of all countries available. A country or territory, identifiable by an ISO 3166 country code.' summary: Get All Countries parameters: @@ -60,6 +61,7 @@ paths: - Countries '/countries/{id}': get: + operationId: get-a-country description: 'Returns a single *Country*. Gets a country. A country or territory, identifiable by an ISO 3166 country code.' summary: Get a Country parameters: @@ -99,6 +101,7 @@ paths: '/countries/{country_id}/states': get: + operationId: get-all-country-states description: |- Returns a list of *States* belonging to a *Country*. A state or province, identifiable by an ISO 3166 subdivision code. @@ -166,6 +169,7 @@ paths: '/countries/{country_id}/states/{id}': get: + operationId: get-a-state description: |- Returns a *State*. A state or province, identifiable by an ISO 3166 subdivision code. @@ -232,10 +236,11 @@ paths: summary: Get a Count of All Countries tags: - Countries - operationId: countriesCount + operationId: get-count-countries description: Returns a count of all countries. '/countries/states/count': get: + operationId: get-count-states responses: '200': $ref: '#/components/responses/countResponse' @@ -245,6 +250,7 @@ paths: description: Returns a count of all states. '/stores/{store_hash}/v2/countries/states': get: + operationId: get-all-states responses: '200': $ref: '#/components/responses/countriesStatesCollectionResponse' @@ -263,18 +269,13 @@ paths: in: query name: page description: The ordered grouping of results to return. - parameters: - - schema: - type: string - name: store_hash - in: path - required: true '/countries/{country_id}/states/count': get: + operationId: get-count-country-states responses: '200': $ref: '#/components/responses/countResponse' - summary: 'Get a Count of Country’s States ' + summary: 'Get a Count of Country’s States' tags: - States description: Returns a count of a country's states. @@ -378,15 +379,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header schemas: diff --git a/reference/marketing.v2.yml b/reference/marketing.v2.yml index ec5a5cce6..69a104ec5 100644 --- a/reference/marketing.v2.yml +++ b/reference/marketing.v2.yml @@ -637,7 +637,7 @@ paths: amount: "10" balance: "0" status: active - template: "Birthday" + template: "birthday.html" message: Happy Birthday! purchase_date: "Tue, 20 Jan 1970 08:45:38 CST" expiry_date: "Mon, 2 Jan 2023 08:45:38 CST" @@ -679,7 +679,7 @@ paths: amount: "10" balance: "0" status: active - template: "Birthday" + template: "birthday.html" message: Happy Birthday! purchase_date: "Tue, 20 Jan 1970 08:45:38 CST" expiry_date: "Mon, 2 Jan 2023 08:45:38 CST" @@ -766,13 +766,15 @@ paths: balance: "500.0000" to_name: Alyss order_id: 1281 - template: "Celebration" + template: "celebration.html" + message: "Celebrate" to_email: test@test.com from_name: Noland from_email: test1@test.com customer_id: 0 expiry_date: "Mon, 2 Jan 2023 08:45:38 CST" purchase_date: "Tue, 20 Jan 1970 08:45:38 CST" + currency_code: "USD" - id: 25 code: 10R-6E3-AO4-RST amount: "700.0000" @@ -780,13 +782,15 @@ paths: balance: "700.0000" to_name: Alyss order_id: 0 - template: "General" + template: "general.html" + message: "Test" to_email: test@test.com from_name: Noland from_email: test1@test.com customer_id: 0 expiry_date: "Mon, 2 Jan 2023 08:45:38 CST" purchase_date: "Tue, 20 Jan 1970 08:45:38 CST" + currency_code: "USD" - id: 27 code: 15R-6E3-AO4-RST amount: "50.0000" @@ -794,13 +798,15 @@ paths: balance: "50.0000" to_name: Lyss order_id: 0 - template: "Celebration" + template: "celebration.html" + message: "Celebrate" to_email: test5@test.com from_name: Somethingelse from_email: test15@test.com customer_id: 0 expiry_date: "Mon, 2 Jan 2023 08:45:38 CST" purchase_date: "Tue, 20 Jan 1970 08:45:38 CST" + currency_code: "USD" post: tags: - Gift Certificates @@ -851,10 +857,11 @@ paths: amount: "10" balance: "0" status: active - template: "Birthday" + template: "birthday.html" message: Happy Birthday! purchase_date: "Tue, 20 Jan 1970 08:45:38 CST" expiry_date: "Mon, 2 Jan 2023 08:45:38 CST" + currency_code: "USD" x-codegen-request-body-name: body delete: tags: @@ -936,8 +943,9 @@ components: properties: name: type: string - description: The name of the coupon. + description: The name of the coupon. The value must be unique. example: Australia Customers Discount + maxLength: 100 type: type: string enum: @@ -977,6 +985,7 @@ components: Value must be unique. Only letters, numbers, white space, underscores, and hyphens are allowed. example: S2549JM0Y + maxLength: 50 applies_to: type: object properties: @@ -1003,13 +1012,11 @@ components: properties: countries: type: string - ? - : type: string shipping_methods: type: array description: This is a list of shipping-method names. A shipping method must be enabled on the store to use it with a coupon. To check which shipping - methods are enabled, please use the [List Shipping Methods](/api/v2#list-shipping-methods) + methods are enabled, please use the [List Shipping Methods](/archive/store-operations/v2-catalog-products/v2-products#list-shipping-methods) endpoint. items: type: string @@ -1090,6 +1097,10 @@ components: description: 'Integer value denoting whether or not the banner is visible on the storefront: 1 = visible; 0 = not visible' example: "1" + item_id: + type: string + description: If the banner is on a specific category or brand page, then the item_id will correspond the category or brand ID. + example: "35" x-internal: false banner_Full: title: banner_Full @@ -1105,23 +1116,12 @@ components: date_created: type: string description: Date the banner is created. - item_id: - type: string - description: If the banner is on a specific category or brand page then - the `item_id` will correspond the category or brand id. - example: "0" - $ref: '#/components/schemas/banner_Base' x-internal: false banner_Put: title: banner_Put allOf: - type: object - properties: - item_id: - type: string - description: If the banner is on a specific category or brand page then - the `item_id` will correspond the category or brand id. - example: "0" - $ref: '#/components/schemas/banner_Base' x-internal: false giftCertificate_Base: @@ -1164,7 +1164,7 @@ components: properties: id: type: integer - description: The ID of the gift certificate.This is a READ-ONLY field; + description: The ID of the gift certificate. This is a READ-ONLY field; do not set or modify its value in a POST or PUT request. example: 1 customer_id: @@ -1191,14 +1191,14 @@ components: template: type: string description: The email theme to use in the message sent to the recipient. - example: Celebration + example: celebration.html enum: - - Birthday - - Girl - - Boy - - Celebration - - Christmas - - General + - birthday.html + - girl.html + - boy.html + - celebration.html + - christmas.html + - general.html message: type: string description: Text that will be sent to the recipient, such as “Congratulations.” @@ -1218,6 +1218,13 @@ components: - pending - disabled - expired + currency_code: + type: string + description: |- + A currency code, following the ISO 4217 standard. The currency has to exist in the store first. + + Gift Certificates can only be used if the transactional currency of the cart is the same as the one defined in the gift certificate. If this value is not provided, the gift certificate is created using the store's default transactional currency. + example: USD x-internal: false giftCertificate_Put: title: giftCertificate_Put @@ -1227,7 +1234,7 @@ components: properties: balance: type: string - description: Remaining value of the gift certificate. If not set, will + description: The remaining value of the gift certificate. If not set, will default to the amount. example: "0" purchase_date: @@ -1246,14 +1253,14 @@ components: template: type: string description: The email theme to use in the message sent to the recipient. - example: Celebration + example: celebration.html enum: - - Birthday - - Boy - - Girl - - Celebration - - Christmas - - General + - birthday.html + - boy.html + - girl.html + - celebration.html + - christmas.html + - general.html message: type: string description: Text that will be sent to the recipient, such as “Congratulations.” @@ -1273,6 +1280,13 @@ components: - pending - expired - disabled + currency_code: + type: string + description: |- + A currency code, following the ISO 4217 standard. The currency has to exist in the store first. + + Gift Certificates can only be used if the transactional currency of the cart is the same as the one defined in the gift certificate. If this value is not provided, the gift certificate is created using the store's default transactional currency. + example: USD x-internal: false giftCertificate_Post: title: giftCertificate_Post @@ -1302,14 +1316,14 @@ components: template: type: string description: The email theme to use in the message sent to the recipient. - example: Celebration + example: celebration.html enum: - - Birthday - - Boy - - Girl - - Celebration - - Christmas - - General + - birthday.html + - boy.html + - girl.html + - celebration.html + - christmas.html + - general.html message: maxLength: 250 type: string @@ -1333,9 +1347,9 @@ components: currency_code: type: string description: |- - A currency code, following the ISO 4217 standard. The currency has to exists in the store first. + A currency code, following the ISO 4217 standard. The currency has to exist in the store first. - Gift Certificates can only be used if the transactional currency of the cart is the same to the one defined in the gift certificate. If this value is not provided, the gift certificate is created using the store's default transactional currency + Gift Certificates can only be used if the transactional currency of the cart is the same as the one defined in the gift certificate. If this value is not provided, the gift certificate is created using the store's default transactional currency. example: USD x-internal: false responses: @@ -1488,7 +1502,7 @@ components: balance: "500.0000" to_name: Alyss order_id: 1281 - template: "Girl" + template: "girl.html" to_email: test@test.com from_name: Noland from_email: test1@test.com @@ -1502,7 +1516,7 @@ components: balance: "700.0000" to_name: Alyss order_id: 0 - template: "Boy" + template: "boy.html" to_email: test@test.com from_name: Noland from_email: test1@test.com @@ -1516,7 +1530,7 @@ components: balance: "50.0000" to_name: Lyss order_id: 0 - template: "Christmas" + template: "christmas.html" to_email: test5@test.com from_name: Somethingelse from_email: test15@test.com @@ -1541,7 +1555,7 @@ components: amount: "10" balance: "0" status: active - template: "Birthday" + template: "birthday.html" message: Happy Birthday! purchase_date: "Tue, 20 Jan 1970 08:45:38 CST" expiry_date: "Mon, 2 Jan 2023 08:45:38 CST" @@ -1560,15 +1574,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header diff --git a/reference/orders.sf.yml b/reference/orders.sf.yml index 2f9f7c455..99f339cae 100644 --- a/reference/orders.sf.yml +++ b/reference/orders.sf.yml @@ -4,9 +4,9 @@ info: description: |- Get order data immediately after an order is placed on the storefront. - For info about API accounts, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). + For info about API accounts, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). - For info about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#same-origin-cors-authentication). + For info about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#same-origin-cors-authentication). version: '' termsOfService: 'https://www.bigcommerce.com/terms' contact: @@ -44,6 +44,22 @@ paths: exclusiveMinimum: false type: integer format: int32 + - name: include + in: query + description: Sub-resources to include in an Order, in a comma-separated list. The ID and the specified fields will be returned. + explode: false + schema: + type: array + items: + type: string + enum: + - lineItems + - billingAddress + - coupons + - currency + - taxes + - payments + - consignments responses: '200': description: '' @@ -261,6 +277,9 @@ components: type: number description: Quantity of this item. format: double + brand: + type: string + description: The product's brand. isTaxable: type: boolean description: Whether the item is taxable. @@ -297,7 +316,7 @@ components: format: double type: type: string - description: the product type - physical or digital + description: the product type - physical or digital. addedByPromotion: type: boolean description: Whether this item has been added automatically by a promotion. @@ -360,6 +379,9 @@ components: type: number description: Quantity of this item. format: double + brand: + type: string + description: The item's brand. isTaxable: type: boolean description: Whether the item is taxable. @@ -672,6 +694,9 @@ components: properties: {} discountAmount: type: integer + brand: + type: string + description: The product's brand. listPrice: type: number salePrice: diff --git a/reference/orders.v2.oas2.yml b/reference/orders.v2.oas2.yml index 99b6a1515..6cd6cadb1 100644 --- a/reference/orders.v2.oas2.yml +++ b/reference/orders.v2.oas2.yml @@ -7,7 +7,7 @@ info: ## Order - The Order object contains a record of the purchase agreement between a shopper and a merchant. To learn more about creating orders, see [Orders API Guide](/api-docs/orders/orders-api-overview). + The Order object contains a record of the purchase agreement between a shopper and a merchant. To learn more about creating orders, see [Orders API Guide](/docs/store-operations/orders). ### Currency Fields @@ -72,15 +72,17 @@ paths: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/order_id_path' get: - description: 'Gets an *Order*. To learn more about creating or updating orders, see [Orders Overview](/api-docs/orders/orders-api-overview).' + description: Gets an *Order*. To learn more about creating or updating orders, see [Orders Overview](/docs/store-operations/orders). summary: Get an Order tags: - Orders + parameters: + - $ref: '#/components/parameters/order_includes' responses: '200': $ref: '#/components/responses/order_Resp' '404': - description: '"The requested resource was not found."' + description: "The requested resource was not found." content: application/json: schema: {} @@ -95,7 +97,7 @@ paths: To remove a product from an order, set that product’s `quantity` to `0`. - To learn more about creating or updating orders, see [Orders Overview](/api-docs/orders/orders-api-overview). + To learn more about creating or updating orders, see [Orders Overview](/docs/store-operations/orders). summary: Update an Order tags: - Orders @@ -154,8 +156,8 @@ paths: - product_id: 123 quantity: 5 product_options: - id: 56 - value: 12 + - id: 56 + value: 12 price_inc_tax: 12.45 price_ex_tax: 10.12 Adding a new product to order: @@ -169,11 +171,12 @@ paths: Removing a product from an order: value: products: - - product_id: 123 - quantity: 0 + - id: 117 + product_id: 123 + quantity: 1 product_options: - id: 56 - value: 12 + - id: 56 + value: 12 price_inc_tax: 12.45 price_ex_tax: 10.12 required: true @@ -182,7 +185,7 @@ paths: $ref: '#/components/responses/order_Resp' operationId: updateAnOrder delete: - description: 'Archives an order. To remove a single product from an order, see `PUT /orders/{order_id}`.' + description: Archives an order. To remove a single product from an order, see `PUT /orders/{order_id}`. summary: Archive an Order tags: - Orders @@ -211,7 +214,9 @@ paths: **Notes** - The default sort is by order id, from lowest to highest. + * The default sort is by order id, from lowest to highest. + * By default, requests sent without parameters will only return 50 orders. + tags: - Orders parameters: @@ -233,6 +238,7 @@ paths: - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/is_deleted' - $ref: '#/components/parameters/channel_id' + - $ref: '#/components/parameters/order_includes' responses: '200': $ref: '#/components/responses/orderCollection_Resp' @@ -240,7 +246,7 @@ paths: operationId: getAllOrders post: description: |- - Creates an *Order*. To learn more about creating or updating orders, see [Orders Overview](/api-docs/orders/orders-api-overview). + Creates an *Order*. To learn more about creating or updating orders, see [Orders Overview](/docs/store-operations/orders). Create an order with an existing catalog product or a custom product. @@ -267,14 +273,35 @@ paths: - Orders parameters: - $ref: '#/components/parameters/ContentType' + - $ref: '#/components/parameters/order_includes' requestBody: content: application/json: schema: $ref: '#/components/schemas/order_Post' examples: + Product with Variants: + value: + status_id: 0 + customer_id: 1 + billing_address: + first_name: Jane + last_name: Doe + street_1: 123 Main Street + city: Austin + state: Texas + zip: '78751' + country: United States + country_iso2: US + email: janedoe@example.com + products: + - product_id: 118 + quantity: 1 + variant_id: 93 Custom Product: value: + status_id: 0 + customer_id: 1 billing_address: first_name: Jane last_name: Doe @@ -406,6 +433,8 @@ paths: summary: Delete All Orders tags: - Orders + parameters: + - $ref: '#/components/parameters/limit' responses: '204': description: '' @@ -441,9 +470,10 @@ paths: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/order_id_path' get: - description: 'Lists all order products on an order using `order_id`. By default, items sort from lowest to highest according to a newly created ID, separate from the `order_id` and the `product_id`.' + description: Lists 50 order products on an order using `order_id`. By default, items sort from lowest to highest according to a newly created ID, separate from the `order_id` and the `product_id`. summary: List Order Products parameters: + - $ref: '#/components/parameters/ContentType' - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/limit' responses: @@ -554,7 +584,7 @@ paths: - $ref: '#/components/parameters/limit' - in: query name: details - description: 'To return detailed tax information, pass in the details query.' + description: To return detailed tax information, pass in the details query. schema: type: string default: 'true' @@ -582,17 +612,23 @@ paths: operationId: getAllOrderShipments post: description: | - Creates an *Order Shipment*. For more details, see [Shipping an Order](/api-docs/orders/orders-api-overview#creating-order-shipments). + Creates an *Order Shipment*. For more details, see [Shipping an Order](/docs/store-operations/orders#creating-order-shipments). **Required Fields** * order_address_id * items **Usage notes** + + There are three methods for generating a tracking link for a shipment: + + 1. Use `shipping_provider` and `tracking_number`: This generates an automatic tracking link that you can click from the BigCommerce control panel and customer-facing emails. The `generated_tracking_link` property in the API response represents this tracking link. The `tracking_link` property in the API response will remain empty. + + 2. Use `tracking_carrier` and `tracking_number`: This also creates an automatic tracking link that you can click in both the BigCommerce control panel and customer-facing emails. Like the previous method, the `generated_tracking_link` property in the API response represents this tracking link. The `tracking_link` property in the API response will remain empty. + + 3. Supply a custom `tracking_link`: By providing a value for the `tracking_link` property, you can use your own tracking link within the BigCommerce control panel and in customer-facing emails. The API response will return your supplied tracking link as part of the `tracking_link` property in the response. In situations when there isn't a `generated_tracking_link`, the property in the API response will remain empty. - Presuming that a valid carrier code is used, a tracking link is generated if either `shipping_provider` or `tracking_carrier` is supplied alongside a tracking number. Providing only the tracking number will result in non-clickable text in the customer facing email. - - Acceptable values for `shipping_provider` include an empty string (`""`), auspost, canadapost, endicia, usps, fedex, royalmail, ups, upsready, upsonline, or shipperhq. + Acceptable values for `shipping_provider` include an empty string (`""`), `auspost`, `carrier_{your_carrier_id}` (only used if the carrier is a [third-party Shipping Provider](/docs/integrations/shipping)), `canadapost`, `endicia`, `usps`, `fedex`, `royalmail`, `ups`, `upsready`, `upsonline`, or `shipperhq`. Acceptable values for `tracking_carrier` include an empty string (`""`) or one of the valid [tracking-carrier values](https://github.com/bigcommerce/dev-docs/blob/master/assets/csv/tracking_carrier_values.csv). summary: Create Order Shipment @@ -646,7 +682,7 @@ paths: $ref: '#/components/responses/orderShipment_Resp' operationId: getOrderShipment summary: Get a Shipment - description: 'Gets an order shipment. ' + description: Gets an order shipment. put: description: Updates an existing shipment associated with an order. summary: Update a Shipment @@ -662,7 +698,7 @@ paths: value: tracking_number: EJ958083578US order_address_id: 1 - shipping_provider: '' + shipping_provider: fedex items: - order_product_id: 15 quantity: 2 @@ -868,18 +904,21 @@ paths: tags: - Order Shipping Addresses Quotes operationId: getShippingQuotes - '/stores/{store_hash}/v2/orders/{order_id}/consignments': + '/orders/{order_id}/consignments': parameters: - schema: type: string name: order_id in: path required: true - - schema: + - name: include + in: query + description: |- + * `consignments.line_items` - include the response returned from the request to the `/orders/{order_id}/products` endpoint in consignments. + schema: type: string - name: store_hash - in: path - required: true + enum: + - consignments.line_items get: summary: Get Consignments tags: @@ -920,9 +959,8 @@ paths: operationId: get-orders-orderId-consignments description: 'Get all consignments for an order. ' parameters: - - $ref: '#/components/parameters/store_hash' - $ref: '#/components/parameters/order_id_path' - '/stores/{store_hash}/v2/orders/{order_id}/consignments/shipping/{shipping_consignment_id}/shipping_quotes': + '/orders/{order_id}/consignments/shipping/{shipping_consignment_id}/shipping_quotes': get: summary: Get Consignment Shipping Quotes tags: @@ -954,22 +992,22 @@ paths: timestamp: 'Fri, 24 Jun 2022 03:52:03 +0000' shipping_provider_id: bcrealtime shipping_provider_quote: - rate: - value: '107.32' - unit: USD - transitTime: '1' - name: Priority Overnight - signatureConfirmationFee: {} - carrierName: '' - carrierCode: {} - code: {} - deliveryMessage: '' - labelSizes: [] - insuredMailFee: {} - dates: [] - rateId: {} - description: '' - additionalInfo: {} + - rate: + value: '107.32' + unit: USD + transitTime: '1' + name: Priority Overnight + signatureConfirmationFee: {} + carrierName: '' + carrierCode: {} + code: {} + deliveryMessage: '' + labelSizes: [] + insuredMailFee: {} + dates: [] + rateId: {} + description: '' + additionalInfo: {} provider_code: fedex carrier_code: '' rate_code: '' @@ -982,7 +1020,6 @@ paths: Get all shipping quotes persisted on an order for a shipping consignment. This is a read-only endpoint whose response depends on the shipping quote. You can only generate a shipping quote using the storefront at this time. Orders that are created in the control panel, or using the API, return a 204 status response since you can't generate a shipping quote during that process. parameters: - - $ref: '#/components/parameters/store_hash' - $ref: '#/components/parameters/order_id_path' - $ref: '#/components/parameters/shipping_consignment_id' components: @@ -991,7 +1028,7 @@ components: name: Accept in: header required: true - description: 'The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body.' + description: The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body. schema: type: string default: 'application/json' @@ -999,7 +1036,7 @@ components: name: Content-Type in: header required: true - description: 'The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the request body.' + description: The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the request body. schema: type: string default: 'application/json' @@ -1069,7 +1106,7 @@ components: payment_method: name: payment_method in: query - description: The payment method used on the order. + description: The display name of the payment method used on the order. schema: type: string enum: @@ -1137,7 +1174,7 @@ components: sort: in: query name: sort - description: 'Field and direction to sort orders. To specify the direction, add `:asc` or `:desc` to the end of the query parameter. E.g. `sort=date_created:desc`.' + description: Field and direction to sort orders. To specify the direction, add `:asc` or `:desc` to the end of the query parameter. e.g., `sort=date_created:desc`. schema: type: string enum: @@ -1197,12 +1234,6 @@ components: description: The Channel ID of the Order. schema: type: integer - store_hash: - name: store_hash - schema: - type: string - in: path - required: true shipping_consignment_id: name: shipping_consignment_id in: path @@ -1210,6 +1241,18 @@ components: description: Shipping consignment ID. schema: type: integer + order_includes: + name: include + in: query + description: |- + * `consignments` - include the response returned from the request to the `/orders/{order_id}/consignments` endpoint. + + * `consignments.line_items` - include the response returned from the request to the `/orders/{order_id}/products` endpoint in consignments. This implies `include=consignments`. + schema: + type: string + enum: + - consignments + - consignments.line_items responses: orderStatusCollection_Resp: description: Get All Order Status Collection Response. @@ -1226,25 +1269,25 @@ components: name: Incomplete system_label: Incomplete custom_label: Incomplete - Testing - system_description: 'An incomplete order happens when a shopper reached the payment page, but did not complete the transaction.' + system_description: An incomplete order happens when a shopper reached the payment page, but did not complete the transaction. order: 0 - id: 1 name: Pending system_label: Pending custom_label: Pending - system_description: 'Customer started the checkout process, but did not complete it.' + system_description: Customer started the checkout process, but did not complete it. order: 1 - id: 2 name: Shipped system_label: Shipped custom_label: Shipped - system_description: 'Order has been shipped, but receipt has not been confirmed; seller has used the Ship Items action.' + system_description: Order has been shipped, but receipt has not been confirmed; seller has used the Ship Items action. order: 8 - id: 3 name: Partially Shipped system_label: Partially Shipped custom_label: Partially Shipped - system_description: 'Only some items in the order have been shipped, due to some products being pre-order only or other reasons.' + system_description: Only some items in the order have been shipped, due to some products being pre-order only or other reasons. order: 6 - id: 4 name: Refunded @@ -1256,31 +1299,31 @@ components: name: Cancelled system_label: Cancelled custom_label: Cancelled - system_description: 'Seller has cancelled an order, due to a stock inconsistency or other reasons.' + system_description: Seller has cancelled an order, due to a stock inconsistency or other reasons. order: 9 - id: 6 name: Declined system_label: Declined custom_label: Declined - system_description: 'Seller has marked the order as declined for lack of manual payment, or other reasons.' + system_description: Seller has marked the order as declined for lack of manual payment, or other reasons. order: 10 - id: 7 name: Awaiting Payment system_label: Awaiting Payment custom_label: Awaiting Payment - system_description: 'Customer has completed checkout process, but payment has yet to be confirmed.' + system_description: Customer has completed checkout process, but payment has yet to be confirmed. order: 2 - id: 8 name: Awaiting Pickup system_label: Awaiting Pickup custom_label: Awaiting Pickup - system_description: 'Order has been pulled, and is awaiting customer pickup from a seller-specified location.' + system_description: Order has been pulled, and is awaiting customer pickup from a seller-specified location. order: 5 - id: 9 name: Awaiting Shipment system_label: Awaiting Shipment custom_label: Awaiting Shipment - system_description: 'Order has been pulled and packaged, and is awaiting collection from a shipping provider.' + system_description: Order has been pulled and packaged, and is awaiting collection from a shipping provider. order: 4 - id: 10 name: Completed @@ -1421,7 +1464,7 @@ components: url: 'https://api.bigcommerce.com/stores/{store_hash}/v2/orders/100/coupons' resource: /orders/100/coupons external_id: null - external_merchant_id: {} + external_merchant_id: null tax_provider_id: BasicTaxProvider store_default_currency_code: '' store_default_to_transactional_exchange_rate: '1.0000000000' @@ -1442,21 +1485,21 @@ components: name: Incomplete system_label: Incomplete custom_label: Incomplete - Testing - system_description: 'An incomplete order happens when a shopper reached the payment page, but did not complete the transaction.' + system_description: An incomplete order happens when a shopper reached the payment page, but did not complete the transaction. count: 15 sort_order: 0 - id: 1 name: Pending system_label: Pending custom_label: Pending - system_description: 'Customer started the checkout process, but did not complete it.' + system_description: Customer started the checkout process, but did not complete it. count: 4 sort_order: 1 - id: 7 name: Awaiting Payment system_label: Awaiting Payment custom_label: Awaiting Payment - system_description: 'Customer has completed checkout process, but payment has yet to be confirmed.' + system_description: Customer has completed checkout process, but payment has yet to be confirmed. count: 48 sort_order: 2 - id: 11 @@ -1470,21 +1513,21 @@ components: name: Awaiting Shipment system_label: Awaiting Shipment custom_label: Awaiting Shipment - system_description: 'Order has been pulled and packaged, and is awaiting collection from a shipping provider.' + system_description: Order has been pulled and packaged, and is awaiting collection from a shipping provider. count: 1 sort_order: 4 - id: 8 name: Awaiting Pickup system_label: Awaiting Pickup custom_label: Awaiting Pickup - system_description: 'Order has been pulled, and is awaiting customer pickup from a seller-specified location.' + system_description: Order has been pulled, and is awaiting customer pickup from a seller-specified location. count: 0 sort_order: 5 - id: 3 name: Partially Shipped system_label: Partially Shipped custom_label: Partially Shipped - system_description: 'Only some items in the order have been shipped, due to some products being pre-order only or other reasons.' + system_description: Only some items in the order have been shipped, due to some products being pre-order only or other reasons. count: 1 sort_order: 6 - id: 10 @@ -1498,21 +1541,21 @@ components: name: Shipped system_label: Shipped custom_label: Shipped - system_description: 'Order has been shipped, but receipt has not been confirmed; seller has used the Ship Items action.' + system_description: Order has been shipped, but receipt has not been confirmed; seller has used the Ship Items action. count: 14 sort_order: 8 - id: 5 name: Cancelled system_label: Cancelled custom_label: Cancelled - system_description: 'Seller has cancelled an order, due to a stock inconsistency or other reasons.' + system_description: Seller has cancelled an order, due to a stock inconsistency or other reasons. count: 5 sort_order: 9 - id: 6 name: Declined system_label: Declined custom_label: Declined - system_description: 'Seller has marked the order as declined for lack of manual payment, or other reasons.' + system_description: Seller has marked the order as declined for lack of manual payment, or other reasons. count: 0 sort_order: 10 - id: 4 @@ -1615,10 +1658,10 @@ components: street_2: '' city: Austin state: Texas - zip: 78108 + zip: '78108' country: United States country_iso2: US - phone: 1234567890 + phone: '1234567890' email: janedoe@example.com form_fields: - name: Delivery Instructions @@ -1654,51 +1697,51 @@ components: date_shipped: '' status_id: 11 status: Awaiting Fulfillment - subtotal_ex_tax: 924.47 - subtotal_inc_tax: 1000.74 - subtotal_tax: 76.27 - base_shipping_cost: 8 - shipping_cost_ex_tax: 7.39 - shipping_cost_inc_tax: 8 - shipping_cost_tax: 0.61 + subtotal_ex_tax: '924.47' + subtotal_inc_tax: '1000.74' + subtotal_tax: '76.27' + base_shipping_cost: '8' + shipping_cost_ex_tax: '7.39' + shipping_cost_inc_tax: '8' + shipping_cost_tax: '0.61' shipping_cost_tax_class_id: 0 - base_handling_cost: 0 - handling_cost_ex_tax: 0 - handling_cost_inc_tax: 0 - handling_cost_tax: 0 + base_handling_cost: '0' + handling_cost_ex_tax: '0' + handling_cost_inc_tax: '0' + handling_cost_tax: '0' handling_cost_tax_class_id: 0 - base_wrapping_cost: 0 - wrapping_cost_ex_tax: 0 - wrapping_cost_inc_tax: 0 - wrapping_cost_tax: 0 + base_wrapping_cost: '0' + wrapping_cost_ex_tax: '0' + wrapping_cost_inc_tax: '0' + wrapping_cost_tax: '0' wrapping_cost_tax_class_id: 0 - total_ex_tax: 931.86 - total_inc_tax: 1008.74 + total_ex_tax: '931.86' + total_inc_tax: '1008.74' total_tax: 76.88 items_total: 11 items_shipped: 0 payment_method: Test Payment Gateway payment_provider_id: '' payment_status: captured - refunded_amount: 0 + refunded_amount: '0' order_is_digital: false - store_credit_amount: 0 - gift_certificate_amount: 0 + store_credit_amount: '0' + gift_certificate_amount: '0' ip_address: 70.112.53.67 geoip_country: United States geoip_country_iso2: US currency_id: 1 currency_code": USD - currency_exchange_rate: 1 + currency_exchange_rate: '1' default_currency_id: 1 default_currency_code: USD staff_notes: BIN-45 customer_message: Custom Journal Added - discount_amount: 0 + discount_amount: '0' coupon_discount": 0 shipping_address_count: 1 is_deleted: false - ebay_order_id: 0 + ebay_order_id: '0' cart_id: 8b84f622-faf1-4c10-887b-f5dff2f9eaf4 billing_address: first_name: Jane @@ -1714,13 +1757,13 @@ components: phone: '1234567890' email: janedoe@email.com form_fields: - name: Delivery Instructions - value: Leave in backyard + - name: Delivery Instructions + value: Leave in backyard is_email_opt_in: false credit_card_type: {} order_source: manual channel_id: 1 - external_source: {} + external_source: '' products: url: 'https://api.bigcommerce.com/stores/{store_hash}/v2/orders/247/products' resource: /orders/247/products @@ -1730,11 +1773,11 @@ components: coupons: url: 'https://api.bigcommerce.com/stores/{store_hash}/v2/orders/247/coupons' resource: /orders/247/coupons - external_id: {} - external_merchant_id: {} + external_id: null + external_merchant_id: null tax_provider_id: BasicTaxProvider store_default_currency_code: USD - store_default_to_transactional_exchange_rate: 1 + store_default_to_transactional_exchange_rate: '1' custom_status: Awaiting Fulfillment customer_locale: en external_order_id: external-order-id @@ -1807,9 +1850,9 @@ components: total_tax: '9.2400' weight: '1.0000' quantity: 1 - base_cost_price: '0.0000' - cost_price_inc_tax: '0.0000' - cost_price_ex_tax: '0.0000' + base_cost_price: '50.0000' + cost_price_inc_tax: '50.0000' + cost_price_ex_tax: '50.0000' cost_price_tax: '0.0000' is_refunded: false quantity_refunded: 0 @@ -1897,6 +1940,7 @@ components: display_style: Pick list configurable_fields: [] gift_certificate_id: null + discounted_total_inc_tax: '63.6400' - id: 66 order_id: 149 product_id: 86 @@ -1914,9 +1958,9 @@ components: total_tax: '0.0000' weight: '0.0000' quantity: 1 - base_cost_price: '0.0000' - cost_price_inc_tax: '0.0000' - cost_price_ex_tax: '0.0000' + base_cost_price: '50.0000' + cost_price_inc_tax: '50.0000' + cost_price_ex_tax: '50.0000' cost_price_tax: '0.0000' is_refunded: false quantity_refunded: 0 @@ -1945,6 +1989,7 @@ components: product_options: [] configurable_fields: [] gift_certificate_id: null + discounted_total_inc_tax: '0.0000' orderProductLineItem_Resp: description: '' content: @@ -1952,7 +1997,7 @@ components: schema: $ref: '#/components/schemas/orderProducts' examples: - response: + Product: value: id: 116 order_id: 181 @@ -1974,9 +2019,65 @@ components: total_tax: '5.2800' weight: '2.0000' quantity: 1 - base_cost_price: '0.0000' - cost_price_inc_tax: '0.0000' - cost_price_ex_tax: '0.0000' + base_cost_price: '50.0000' + cost_price_inc_tax: '50.0000' + cost_price_ex_tax: '50.0000' + cost_price_tax: '0.0000' + is_refunded: false + quantity_refunded: 0 + refund_amount: '0.0000' + return_id: 0 + wrapping_name: '' + base_wrapping_cost: '0.0000' + wrapping_cost_ex_tax: '0.0000' + wrapping_cost_inc_tax: '0.0000' + wrapping_cost_tax: '0.0000' + wrapping_message: '' + quantity_shipped: 0 + event_name: null + event_date: null + fixed_shipping_cost: '0.0000' + ebay_item_id: '' + ebay_transaction_id: '' + option_set_id: null + parent_order_product_id: null + is_bundled_product: false + bin_picking_number: '' + external_id: null + fulfillment_source: '' + brand: BigCommerce + applied_discounts: [] + product_options: [] + discounted_total_inc_tax: '37.2300' + Product with file upload: + value: + id: 35 + order_id: 125 + product_id: 127 + variant_id: 99 + order_address_id: 18 + name: Journal + name_customer: Journal + name_merchant: Journal + sku: Jour-BLK + upc: '' + type: physical + base_price: '45.0000' + price_ex_tax: '41.5700' + price_inc_tax: '45.0000' + price_tax: '3.4300' + base_total: '45.0000' + total_ex_tax: '41.5700' + total_inc_tax: '45.0000' + total_tax: '3.4300' + weight: '0.0000' + width: '0.0000' + height: '0.0000' + depth: '0.0000' + quantity: 1 + base_cost_price: '50.0000' + cost_price_inc_tax: '50.0000' + cost_price_ex_tax: '50.0000' cost_price_tax: '0.0000' is_refunded: false quantity_refunded: 0 @@ -2003,20 +2104,20 @@ components: brand: BigCommerce applied_discounts: [] product_options: - - id: 89 - option_id: 90 - order_product_id: 116 - product_option_id: 227 - display_name: Product Pick List - display_name_customer: Product Pick List - display_name_merchant: Product Pick List - display_value: 1L Le Parfait Jar - display_value_customer: 1L Le Parfait Jar - display_value_merchant: 1L Le Parfait Jar - value: '197' - type: Product Pick List - name: ProductPickList - display_style: Pick list + - id: 18 + option id: 38 + order_product_id: 35 + product_option_id: 121 + display_name: Custom Logo Engraving + display_name_customer: Custom Logo Engraving + display_name_merchant: Custom Logo Engraving + display_value: BigCommerceLogo.jpeg + display_value_customer: BigCommerceLogo.jpeg + display_value_merchant: BigCommerceLogo.jpeg + value: "{\"originalName\":\"BigCommerceLogo.jpeg\",\"temporaryPath\":\"121_fbfb71dfc5a5d911f62d8e35dedd6e45.jpeg\",\"path\":\"f606efcae7e179970b19c3658142c5d0.jpeg\"}" + type: File Upload + name: Custom Logo Engraving + display_style: "" configurable_fields: [] gift_certificate_id: null Custom Product: @@ -2045,9 +2146,9 @@ components: height: '0.0000' depth: '0.0000' quantity: 1 - base_cost_price: '0.0000' - cost_price_inc_tax: '0.0000' - cost_price_ex_tax: '0.0000' + base_cost_price: '50.0000' + cost_price_inc_tax: '50.0000' + cost_price_ex_tax: '50.0000' cost_price_tax: '0.0000' is_refunded: false quantity_refunded: 0 @@ -2061,7 +2162,7 @@ components: wrapping_message: '' quantity_shipped: 0 event_name: null - event_date: '' + event_date: null fixed_shipping_cost: '0.0000' ebay_item_id: '' ebay_transaction_id: '' @@ -2102,9 +2203,9 @@ components: height: '3.0000' depth: '3.0000' quantity: 4 - base_cost_price: '0.0000' - cost_price_inc_tax: '0.0000' - cost_price_ex_tax: '0.0000' + base_cost_price: '50.0000' + cost_price_inc_tax: '50.0000' + cost_price_ex_tax: '50.0000' cost_price_tax: '0.0000' is_refunded: false quantity_refunded: 0 @@ -2117,78 +2218,19 @@ components: wrapping_cost_tax: '0.0000' wrapping_message: '' quantity_shipped: 0 - event_name: {} - event_date: '' + event_name: null + event_date: null fixed_shipping_cost: '0.0000' ebay_item_id: '' ebay_transaction_id: '' option_set_id: 68 - parent_order_product_id: {} + parent_order_product_id: null is_bundled_product: false bin_picking_number: '' - external_id: {} + external_id: null fulfillment_source: '' brand: BigCommerce applied_discounts: [] - product_options: - value: - - id: 143 - option_id: 96 - order_product_id: 240 - product_option_id: 242 - display_name: Color - display_name_customer: Color - display_name_merchant: Color - display_value: Red - display_value_customer: Red - display_value_merchant: Red - value: '211' - type: Swatch - name: Color1549572910-201 - display_style: '' - - id: 144 - option_id: 114 - order_product_id: 240 - product_option_id: 263 - display_name: PickList PriceList - display_name_customer: PickList PriceList - display_name_merchant: PickList PriceList - display_value: Able Brewing System - display_value_customer: Able Brewing System - display_value_merchant: Able Brewing System - value: '237' - type: Product Pick List - name: PickList-PriceList1549572910-201 - display_style: Pick list with photos - - id: 145 - option_id: 97 - order_product_id: 240 - product_option_id: 243 - display_name: T-Shirt Size - display_name_customer: T-Shirt Size - display_name_merchant: T-Shirt Size - display_value: Small T-Shirt - display_value_customer: Small T-Shirt - display_value_merchant: Small T-Shirt - value: '214' - type: Multiple choice - name: T-Shirt-Size1545071633-201 - display_style: Rectangle - - id: 146 - option_id: 105 - order_product_id: 240 - product_option_id: 254 - display_name: Custom Message - display_name_customer: Custom Message - display_name_merchant: Custom Message - display_value: BigCommerce - display_value_customer: BigCommerce - display_value_merchant: BigCommerce - value: BigCommerce - type: Text field - name: Custom-Message1549572912-201 - display_style: '' - configurable_fields: [] orderShipmentCollection_Resp: description: '' content: @@ -2242,6 +2284,8 @@ components: - order_product_id: 188 product_id: 0 quantity: 1 + shipping_provider_display_name: USPS + generated_tracking_link: http://trkcnfrm1.smi.usps.com/PTSInternetWeb/InterLabelInquiry.do?strOrigTrackNum=EJ958083578US - id: 7 order_id: 225 customer_id: 11 @@ -2284,6 +2328,8 @@ components: - order_product_id: 189 product_id: 0 quantity: 1 + shipping_provider_display_name: USPS + generated_tracking_link: http://trkcnfrm1.smi.usps.com/PTSInternetWeb/InterLabelInquiry.do?strOrigTrackNum=EJ958083578US orderShipment_Resp: description: '' content: @@ -2304,6 +2350,7 @@ components: comments: Ready to go... shipping_provider: usps tracking_carrier: '' + tracking_link: '' billing_address: first_name: Jane last_name: Doe @@ -2337,6 +2384,8 @@ components: - order_product_id: 195 product_id: 0 quantity: 1 + shipping_provider_display_name: USPS + generated_tracking_link: http://trkcnfrm1.smi.usps.com/PTSInternetWeb/InterLabelInquiry.do?strOrigTrackNum=EJ958083578US orderCount_Resp: description: '' content: @@ -2547,434 +2596,6 @@ components: priority: 0 priority_amount: '4.4000' line_amount: '4.4000' - actual-order-response: - description: '' - content: - application/json: - schema: - title: Order - example: - id: 113 - customer_id: 1 - date_created: 'Wed, 17 Jan 2018 20:11:21 +0000' - date_modified: 'Wed, 25 Apr 2018 20:20:25 +0000' - date_shipped: '' - status_id: 7 - status: Awaiting Payment - subtotal_ex_tax: '143.9500' - subtotal_inc_tax: '143.9500' - subtotal_tax: '0.0000' - base_shipping_cost: '0.0000' - shipping_cost_ex_tax: '0.0000' - shipping_cost_inc_tax: '0.0000' - shipping_cost_tax: '0.0000' - shipping_cost_tax_class_id: 2 - base_handling_cost: '0.0000' - handling_cost_ex_tax: '0.0000' - handling_cost_inc_tax: '0.0000' - handling_cost_tax: '0.0000' - handling_cost_tax_class_id: 2 - base_wrapping_cost: '0.0000' - wrapping_cost_ex_tax: '0.0000' - wrapping_cost_inc_tax: '0.0000' - wrapping_cost_tax: '0.0000' - wrapping_cost_tax_class_id: 3 - total_ex_tax: '138.9500' - total_inc_tax: '138.9500' - total_tax: '0.0000' - items_total: 2 - items_shipped: 0 - payment_method: Cash on Delivery - payment_provider_id: null - payment_status: '' - refunded_amount: '0.0000' - order_is_digital: false - store_credit_amount: '0.0000' - gift_certificate_amount: '0.0000' - ip_address: 64.183.182.114 - geoip_country: United States - geoip_country_iso2: US - currency_id: 1 - currency_code: USD - currency_exchange_rate: '1.0000000000' - default_currency_id: 1 - default_currency_code: USD - staff_notes: '' - customer_message: '' - discount_amount: '0.0000' - coupon_discount: '5.0000' - shipping_address_count: 1 - is_deleted: false - ebay_order_id: '0' - cart_id: 1cf3da59-1c90-42a9-82fb-2a954743a390 - billing_address: - first_name: Jane - last_name: Does - company: '' - street_1: 123 MainStreet - street_2: '' - city: Austin - state: Texas - zip: '78751' - country: United States - country_iso2: US - phone: '' - email: jane@example.com - form_fields: [] - is_email_opt_in: false - credit_card_type: null - order_source: www - external_source: null - products: - url: 'https://api.bigcommerce.com/stores/{store_hash}/v2/orders/113/products' - resource: /orders/113/products - shipping_addresses: - url: 'https://api.bigcommerce.com/stores/{store_hash}/v2/orders/113/shippingaddresses' - resource: /orders/113/shippingaddresses - coupons: - url: 'https://api.bigcommerce.com/stores/{store_hash}/v2/orders/113/coupons' - resource: /orders/113/coupons - external_id: null - external_merchant_id: null - custom_status: Awaiting Payment - external_order_id: external-order-id - type: object - properties: - id: - description: 'The ID of the order, a read-only value. Do not pass in PUT or POST request.' - example: 118 - type: integer - customer_id: - description: The ID of the customer placing the order; or 0 if it was a guest order. - example: 6 - type: number - date_created: - type: string - description: 'The date the order was created, formatted in the RFC-2822 standard. You set this attribute on Order creation (POST request) to support the migration of historical orders. If you do not provide a value, then it will default to the current date/time. e.g., `Tue, 20 Nov 2012 00:00:00 +0000`' - date_modified: - type: string - description: A read-only value representing the last modification of the order. Do not attempt to modify or set this value in a POST or PUT request. RFC-2822 - date_shipped: - type: string - description: A read-only value representing the date of shipment. Do not attempt to modify or set this value in a POST or PUT request. RFC-2822 - status_id: - description: The status ID of the order. - example: 11 - type: integer - cart_id: - description: 'The cart ID from which this order originated, if applicable. Correlates with the Cart API. This is a read-only field; do not set or modify its value in a POST or PUT request.' - example: a8458391-ef68-4fe5-9ec1-442e6a767364 - type: string - status: - description: 'The status will include one of the (string, optional) - values defined under Order Statuses. This is a read-only value. Do not attempt to modify or set this value in a POST or PUT request.' - example: Awaiting Fulfillment - type: string - custom_status: - description: 'Contains the same (string, optional) - value as the `custom_label` property of the Order Statuses object.' - example: Awaiting Fulfillment - type: string - subtotal_ex_tax: - description: 'Override value for subtotal excluding tax. If specified, the field `subtotal_inc_tax` is also required. (Float, Float-As-String, Integer)' - example: '225.0000' - type: string - subtotal_inc_tax: - description: 'Override value for subtotal including tax. If specified, the field `subtotal_ex_tax` is also required. (Float, Float-As-String, Integer)' - example: '225.0000' - type: string - subtotal_tax: - description: 'A read-only value. Do not attempt to set or modify this value in a POST or PUT request. (Float, Float-As-String, Integer)' - example: '0.0000' - type: string - base_shipping_cost: - description: 'The value of the base shipping cost. (Float, Float-As-String, Integer)' - example: '0.0000' - type: string - shipping_cost_ex_tax: - description: 'The value of shipping cost, excluding tax. (Float, Float-As-String, Integer)' - example: '0.0000' - type: string - shipping_cost_inc_tax: - description: 'The value of shipping cost, including tax. (Float, Float-As-String, Integer)' - example: '0.0000' - type: string - shipping_cost_tax: - description: 'A read-only value. Do not attempt to modify or set this value in a POST or PUT request. (Float, Float-As-String, Integer)' - example: '0.0000' - type: string - shipping_cost_tax_class_id: - description: 'Shipping-cost tax class. A read-only value. Do not attempt to modify or set this value in a POST or PUT request. (NOTE: Value ignored if automatic tax is enabled on the store.)' - example: 2 - type: integer - base_handling_cost: - description: 'The value of the base handling cost. (Float, Float-As-String, Integer)' - example: '0.0000' - type: string - handling_cost_ex_tax: - description: 'The value of the handling cost, excluding tax. (Float, Float-As-String, Integer)' - example: '0.0000' - type: string - handling_cost_inc_tax: - description: 'The value of the handling cost, including tax. (Float, Float-As-String, Integer)' - oneOf: - - type: number - - type: string - handling_cost_tax: - description: 'A read-only value. Do not attempt to modify or set this value in a POST or PUT request. (Float, Float-As-String, Integer)' - example: '0.0000' - type: string - handling_cost_tax_class_id: - description: 'A read-only value. Do not attempt to set or modify this value in a POST or PUT request. (NOTE: Value ignored if automatic tax is enabled on the store.)' - example: 2 - type: integer - base_wrapping_cost: - description: The value of the base wrapping cost. - example: 0 - oneOf: - - type: string - - type: number - wrapping_cost_ex_tax: - description: 'The value of the wrapping cost, excluding tax. (Float, Float-As-String, Integer)' - example: '0.0000' - type: string - wrapping_cost_inc_tax: - description: 'The value of the wrapping cost, including tax. (Float, Float-As-String, Integer)' - example: '0.0000' - type: string - wrapping_cost_tax: - description: 'A read-only value. Do not attempt to modify or set this value in a POST or PUT request. (Float, Float-As-String, Integer)' - example: '0.0000' - type: string - wrapping_cost_tax_class_id: - description: 'A read-only value. Do not attempt to set or modify this value in a POST or PUT request. (NOTE: Value ignored if automatic tax is enabled on the store.)' - example: 3 - type: integer - total_ex_tax: - description: 'Override value for the total, excluding tax. If specified, the field `total_inc_tax` is also required. (Float, Float-As-String, Integer)' - example: '225.0000' - type: string - total_inc_tax: - description: 'Override value for the total, including tax. If specified, the field `total_ex_tax` is also required. (Float, Float-As-String, Integer)' - example: '225.0000' - type: string - total_tax: - description: 'A read-only value. Do not attempt to set or modify this value in a POST or PUT request. (Float, Float-As-String, Integer)' - example: '0.0000' - type: string - items_total: - description: The total number of items in the order. - example: 1 - type: number - items_shipped: - description: The number of items that have been shipped. - example: 0 - type: number - payment_method: - description: 'The payment method for this order. Can be one of the following: `Manual`, `Credit Card`, `cash`, `Test Payment Gateway`, etc.' - example: Cash on Delivery - type: string - payment_provider_id: - description: The external Transaction ID/Payment ID within this order’s payment provider (if a payment provider was used). - example: null - type: string - nullable: true - payment_status: - description: A read-only value. Do not attempt to set or modify this value in a POST or PUT request. - type: string - refunded_amount: - description: 'The amount refunded from this transaction; always returns `0`. (Float, Float-As-String, Integer) ' - example: '0.0000' - type: string - order_is_digital: - description: Whether this is an order for digital products. - example: false - type: boolean - store_credit_amount: - description: 'Represents the store credit that the shopper has redeemed on this individual order. This is a read-only value. Do not pass in a POST or PUT request. (Float, Float-As-String, Integer)' - example: '0.0000' - type: string - gift_certificate_amount: - description: 'A read-only value. Do not pass in a POST or PUT request. (Float, Float-As-String, Integer)' - example: '0.0000' - type: string - ip_address: - description: 'IP Address of the customer, if known.' - example: 12.345.678.910 - type: string - geoip_country: - description: 'The full name of the country where the customer made the purchase, based on the IP.' - example: United States - type: string - geoip_country_iso2: - description: 'The country where the customer made the purchase, in ISO2 format, based on the IP.' - example: US - type: string - currency_id: - description: The display currency ID. May be different from transactional currency. A read-only value. Do not pass in a POST or PUT request. - example: 1 - type: integer - currency_code: - description: The currency code of the display currency used to present prices on the storefront. May be different from transactional currency. A read-only value. Do not pass in a POST or PUT request. - example: USD - type: string - currency_exchange_rate: - description: 'A read-only value. Do not pass in a POST or PUT request. (Float, Float-As-String, Integer)' - example: '1.0000000000' - type: string - default_currency_id: - description: The transactional currency ID. A read-only value. Do not pass in a POST or PUT request. - example: 1 - type: integer - default_currency_code: - description: The currency code of the transactional currency the shopper pays in. A read-only value. Do not pass in a POST or PUT request. - type: string - example: USD - staff_notes: - type: string - description: Any additional notes for staff. - example: Send Saturday - maxLength: 65535 - customer_message: - description: 'Message that the customer entered (number, optional) -o the `Order Comments` box during checkout.' - example: Thank you - type: string - discount_amount: - description: 'Amount of discount for this transaction. (Float, Float-As-String, Integer)' - example: '0.0000' - type: string - coupon_discount: - description: 'A read-only value. Do not pass in a POST or PUT request. (Float, Float-As-String, Integer)' - example: '5.0000' - type: string - shipping_address_count: - type: number - description: The number of shipping addresses associated with this transaction. A read-only value. Do not pass in a POST or PUT request. - is_deleted: - description: 'Boolean value indicates whether the order was deleted (archived). Set to to true to archive an order.' - example: false - type: boolean - is_email_opt_in: - description: Boolean value indicates whether the shopper has selected an opt-in check box (on the checkout page) to receive emails. A read-only value. Do not pass in a POST or PUT request. - example: false - type: boolean - credit_card_type: - description: Credit card type - example: 0 - type: integer - nullable: true - ebay_order_id: - description: 'If the order was placed through eBay, the eBay order number will be included. Otherwise, the value will be `0`.' - example: '0' - type: string - billing_address: - title: Billing Address - type: object - description: Required to create an order. - properties: - first_name: - description: '' - example: Jane - type: string - last_name: - description: '' - example: Doe - type: string - company: - description: '' - type: string - street_1: - description: '' - example: 123 Main Street - type: string - street_2: - description: '' - type: string - city: - description: '' - example: Austin - type: string - state: - description: '' - example: TX - type: string - zip: - description: '' - example: '12345' - type: number - country: - description: '' - example: United States - type: string - country_iso2: - description: '' - example: US - type: string - phone: - description: '' - type: string - email: - description: '' - example: janedoe@example.com - type: string - form_fields: - description: '' - type: array - items: - title: Form Fields - type: object - description: Read-Only. If you have required address form fields they will need to be set as optional before creating an order with the API. - properties: - name: - description: Name of the form field. - type: string - example: License Id - readOnly: true - value: - description: Value of the form field. - type: string - example: 123BAF - readOnly: true - readOnly: true - order_source: - description: Orders submitted from the store’s website will include a `www` value. Orders submitted with the API will be set to `external`. A read-only value. Do not pass in a POST or PUT request. - example: www - type: string - external_source: - description: |- - This value identifies an external system that generated the order and submitted it to BigCommerce using the Orders API. - * When supplying the value, we recommend combining the type of system and vendor, e.g., ERP (Acumatica) or POS (Square). - * If you are migrating historical orders processed on another eCommerce platform to BigCommerce, supply the following code as the value: M-MIG. This code will exclude historical orders from the store’s GMV/order count, which factors into pricing. - * If you do not provide a value, then it will default to null.. - example: null - nullable: true - type: string - products: - $ref: '#/components/schemas/products_Resource' - shipping_addresses: - $ref: '#/components/schemas/shippingAddresses_Resource' - coupons: - $ref: '#/components/schemas/coupons_Resource' - external_id: - description: 'ID of the order in another system. For example, the Amazon Order ID if this is an Amazon order.This field can be updated in a POST request, but using a PUT request to update the order will return a 400 error. The field ''external_id'' cannot be written to. Please remove it from your request before trying again. It cannot be overwritten once set.' - example: null - type: string - nullable: true - external_merchant_id: - description: ID of the merchant. - example: null - type: string - nullable: true - channel_id: - type: integer - example: 1 - description: Shows where the order originated. The channel_id will default to 1. Read-Only. - tax_provider_id: - type: string - description: | - BasicTaxProvider - Tax is set to manual and order is created in the store. - - AvaTaxProvider - Tax is set to automatic and order is created in the store. Used for Avalara. - - "" (empty string) - The order is created with the API, or the tax provider is unknown. 404_Resp: description: Not Found content: @@ -3008,15 +2629,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header schemas: @@ -3057,17 +2678,17 @@ components: example: 120 type: integer code: - description: 'Coupon code, as a string.' + description: Coupon code, as a string. example: S2549JM0Y nullable: true type: string amount: - description: 'Amount of the discount. This information is returned as in integer. Dollar and percentage discounts will return the same. For example, $3 returns as ''3'' while 5% will return as 5. Check the discount type to see what type of discount is available.' - example: 5 - oneOf: + description: Amount of the discount. This information is returned as in integer. Dollar and percentage discounts will return the same. For example, $3 returns as `3` while 5% will return as `5`. Check the discount type to see what type of discount is available. + anyOf: - type: string - type: number - type: integer + example: 5 format: float type: type: integer @@ -3136,15 +2757,15 @@ components: example: physical description: Type of product. base_price: - description: 'The product’s base price. (Float, Float-As-String, Integer)' + description: The product’s base price. (Float, Float-As-String, Integer) example: '54.0000' type: string price_ex_tax: - description: 'The product’s price excluding tax. (Float, Float-As-String, Integer)' + description: The product’s price excluding tax. (Float, Float-As-String, Integer) example: '54.0000' type: string price_inc_tax: - description: 'The product’s price including tax. (Float, Float-As-String, Integer)' + description: The product’s price including tax. (Float, Float-As-String, Integer) example: '54.0000' type: string price_tax: @@ -3158,22 +2779,25 @@ components: example: '0.0000' type: string base_total: - description: 'Total base price. (Float, Float-As-String, Integer)' + description: |- + Total base price. (Float, Float-As-String, Integer) + + **Note**: The `base_total` is affected by the tax options set up in the control panel and is altered on tax-free orders. See more details on how `base_total` is affected by visiting the [Responsive Tax Display Settings](https://support.bigcommerce.com/s/article/Manual-Tax-Setup) overview. If the `base_total` is `$0`, it's due to the store's tax settings. To learn more about tax settings in the control panel, check out this [Tax Settings](https://support.bigcommerce.com/s/article/Tax-Overview?language=en_US#tax-settings) support article. example: '54.0000' type: string total_ex_tax: - description: 'Total base price excluding tax. (Float, Float-As-String, Integer)' + description: Total base price excluding tax. (Float, Float-As-String, Integer) example: '54.0000' type: string total_inc_tax: - description: 'Total base price including tax. (Float, Float-As-String, Integer)' + description: Total base price including tax. (Float, Float-As-String, Integer) example: '54.0000' type: string total_tax: description: |- Total tax applied to products. For example, if quantity if 2, base price is 5 and tax rate is 10%. price_tax will be $.50 and total_tax will be $1.00. - + If there is a manual discount applied total_tax is calculated as the following: `(price_ex_tax - discount)*tax_rate=total_tax`. (Float, Float-As-String, Integer) @@ -3182,25 +2806,25 @@ components: quantity: description: Quantity of the product ordered. example: 1 - type: number + type: integer base_cost_price: - description: 'The product’s cost price. This can be set using the Catalog API. (Float, Float-As-String, Integer) Read Only' - example: '0.0000' + description: The product’s cost price. This can be set using the Catalog API. (Float, Float-As-String, Integer) + example: '50.0000' type: string cost_price_inc_tax: description: |- The product’s cost price including tax. (Float, Float-As-String, Integer) - The cost of your products to you; this is never shown to customers, but can be used for accounting purposes. Read Only - example: '0.0000' + The cost of your products to you; this is never shown to customers, but can be used for accounting purposes. + example: '50.0000' type: string cost_price_ex_tax: description: |- - The products cost price excluding tax. (Float, Float-As-String, Integer) - The cost of your products to you; this is never shown to customers, but can be used for accounting purposes. Read Only - example: '0.0000' + The product cost price excluding tax. (Float, Float-As-String, Integer) + The cost of your products to you; this is never shown to customers, but can be used for accounting purposes. + example: '50.0000' type: string weight: - description: 'Weight of the product. (Float, Float-As-String, Integer)' + description: Weight of the product. (Float, Float-As-String, Integer) example: 1 oneOf: - type: number @@ -3215,9 +2839,13 @@ components: type: boolean description: Whether the product has been refunded. example: false + quantity_refunded: + type: number + description: The total quantity of product refunded from this transaction. + example: 0 refunded_amount: type: string - description: 'The amount refunded from this transaction; always returns `0`. (Float, Float-As-String, Integer) ' + description: The amount refunded from this transaction; always returns `0`. (Float, Float-As-String, Integer) example: '0.0000' deprecated: true return_id: @@ -3228,22 +2856,23 @@ components: description: Name of gift-wrapping option. example: null type: string + nullable: true base_wrapping_cost: - description: 'The value of the base wrapping cost. (Float, Float-As-String, Integer)' + description: The value of the base wrapping cost. (Float, Float-As-String, Integer) example: '0.0000' oneOf: - type: string - type: number wrapping_cost_ex_tax: - description: 'The value of the wrapping cost, excluding tax. (Float, Float-As-String, Integer)' + description: The value of the wrapping cost, excluding tax. (Float, Float-As-String, Integer) example: '0.0000' type: string wrapping_cost_inc_tax: - description: 'The value of the wrapping cost, including tax. (Float, Float-As-String, Integer)' + description: The value of the wrapping cost, including tax. (Float, Float-As-String, Integer) example: '0.0000' type: string wrapping_cost_tax: - description: 'Tax applied to gift-wrapping option. (Float, Float-As-String, Integer)' + description: Tax applied to gift-wrapping option. (Float, Float-As-String, Integer) example: '0.0000' type: string wrapping_message: @@ -3264,7 +2893,7 @@ components: format: date nullable: true fixed_shipping_cost: - description: 'Fixed shipping cost for this product. (Float, Float-As-String, Integer)' + description: Fixed shipping cost for this product. (Float, Float-As-String, Integer) example: '0.0000' type: string ebay_item_id: @@ -3289,6 +2918,14 @@ components: bin_picking_number: description: Bin picking number for the physical product. type: string + external_id: + description: (Read-only) ID of the order in another system. For example, the Amazon order ID if this is an Amazon order. + type: string + nullable: true + readOnly: true + brand: + description: The productʼs brand. + type: string applied_discounts: description: Array of objects containing discounts applied to the product. type: array @@ -3299,10 +2936,6 @@ components: type: array items: $ref: '#/components/schemas/orderProductOptions' - external_id: - description: 'ID of the order in another system. For example, the Amazon Order ID if this is an Amazon order.This field can be updated in a /POST, but using a /PUT to update the order will return a 400 error. The field ''external_id'' cannot be written to. Please remove it from your request before trying again. It cannot be overwritten once set.' - type: string - nullable: true upc: type: string maxLength: 255 @@ -3323,6 +2956,15 @@ components: example: 52 description: ID of the associated gift certificate. nullable: true + discounted_total_inc_tax: + type: string + example: '0.0000' + description: |- + Represent the correct total amount of the line item after deducting all the discounts and including the tax. This number can be used for accounting purpose. + + This makes it easier to have the "shopper paid" value for a line item and api user doesn't have to do any calculation to deduct discount on the client side. + + This field includes all types of discounts (automatic, coupon, manual) and therefore if you use this value, you don't need to deduct any more discounts at line item level or order level. orderCount: title: orderCount example: @@ -3357,42 +2999,44 @@ components: example: 0 base_cost: type: string - description: 'The base value of the order’s items. (Float, Float-As-String, Integer)' + description: The base value of the order’s items. (Float, Float-As-String, Integer) example: '5.0000' cost_ex_tax: type: string example: '0.0000' - description: 'The value of the order’s items, excluding tax. (Float, Float-As-String, Integer)' + description: The value of the order’s items, excluding tax. (Float, Float-As-String, Integer) cost_inc_tax: type: string - description: 'The value of the order’s items, including tax. (Float, Float-As-String, Integer)' + description: The value of the order’s items, including tax. (Float, Float-As-String, Integer) example: '0.0000' cost_tax: type: string - description: 'The tax amount on the order. (Float, Float-As-String, Integer)' + description: The tax amount on the order. (Float, Float-As-String, Integer) example: '0.0000' cost_tax_class_id: type: integer - description: 'The ID of the tax class applied to the product. (NOTE: Value ignored if automatic tax is enabled.)' + description: |- + The ID of the tax class applied to the product. (NOTE: Value ignored if automatic tax is enabled.) example: 2 base_handling_cost: type: string - description: 'The base handling charge. (Float, Float-As-String, Integer)' + description: The base handling charge. (Float, Float-As-String, Integer) example: '0.0000' handling_cost_ex_tax: type: string - description: 'The handling charge, excluding tax. (Float, Float-As-String, Integer)' + description: The handling charge, excluding tax. (Float, Float-As-String, Integer) example: '0.0000' handling_cost_inc_tax: type: string - description: 'The handling charge, including tax. (Float, Float-As-String, Integer)' + description: The handling charge, including tax. (Float, Float-As-String, Integer) example: '0.0000' handling_cost_tax: type: string example: '0.0000' handling_cost_tax_class_id: type: integer - description: 'A read-only value. Do not attempt to set or modify this value in a POST or PUT operation. (NOTE: Value ignored if automatic tax is enabled on the store.)' + description: |- + A read-only value. Do not attempt to set or modify this value in a POST or PUT operation. (NOTE: Value ignored if automatic tax is enabled on the store.) example: 2 shipping_zone_id: type: number @@ -3419,11 +3063,13 @@ components: example: 1 type: integer order_id: - description: 'The unique numeric identifier of the order to which the tax was applied. NOTE: Not included if the store was using the automatic tax feature.' + description: |- + The unique numeric identifier of the order to which the tax was applied. NOTE: Not included if the store was using the automatic tax feature. example: 129 type: integer order_address_id: - description: 'The unique numeric identifier of the order address object associated with the order. NOTE: Not included if the store was using the automatic tax feature.' + description: |- + The unique numeric identifier of the order address object associated with the order. NOTE: Not included if the store was using the automatic tax feature. example: 29 type: integer tax_rate_id: @@ -3431,19 +3077,21 @@ components: example: 1 type: integer tax_class_id: - description: 'The unique numeric identifier of the tax class object. NOTE: Will be 0 if automatic tax was enabled, or if the default tax class was used.' + description: |- + The unique numeric identifier of the tax class object. NOTE: Will be 0 if automatic tax was enabled, or if the default tax class was used. example: 0 type: integer name: description: The name of the tax class object. - example: '"State Tax"' + example: "State Tax" type: string class: - description: 'The name of the type of tax that was applied. NOTE: will be "Automatic Tax" if automatic tax was enabled. Will be "API Tax Override" if the order was created with V2 Orders API.' + description: |- + The name of the type of tax that was applied. NOTE: It will be "Automatic Tax" if automatic tax was enabled. It will be "API Tax Override" if the order was created with V2 Orders API. example: Gift Wrapping type: string rate: - description: 'The tax rate. The priority order in which the tax is applied (Float, Float-As-String, Integer)' + description: The tax rate. The priority order in which the tax is applied (Float, Float-As-String, Integer) example: '8.0000' type: string priority: @@ -3451,11 +3099,11 @@ components: example: 0 type: number priority_amount: - description: 'The amount of tax calculated on the order. (Float, Float-As-String, Integer)' + description: The amount of tax calculated on the order. (Float, Float-As-String, Integer) example: '1.5200' type: string line_amount: - description: '(Float, Float-As-String, Integer)' + description: (Float, Float-As-String, Integer) example: '1.5200' type: string order_product_id: @@ -3506,10 +3154,11 @@ components: type: string shipping_provider: type: string - description: 'Enum of the BigCommerce shipping-carrier integration/module. ' + description: Enum of the BigCommerce shipping-carrier integration/module. enum: - auspost - canadapost + - carrier_{your_carrier_id} (only used if the carrier is a [third-party Shipping Provider](/docs/integrations/shipping)) - endicia - usps - fedex @@ -3517,7 +3166,7 @@ components: - upsready - upsonline - shipperhq - - ' ' + - '' tracking_carrier: type: string title: Tracking Carrier @@ -3526,7 +3175,7 @@ components: Acceptable values for `tracking_carrier` include an empty string (`""`) or one of the valid [tracking-carrier values](https://github.com/bigcommerce/dev-docs/blob/master/assets/csv/tracking_carrier_values.csv). tracking_link: type: string - description: Returns a tracking link from the shipping service. + description: The custom tracking link supplied on POST or PUT shipments. For the auto-generated tracking link see the `generated_tracking_link` property. comments: type: string description: Comments the shipper wishes to add. @@ -3536,7 +3185,8 @@ components: shipping_address: $ref: '#/components/schemas/shippingAddress_Base' items: - description: 'The items in the shipment. This object has the following members, all integer: order_product_id (required), quantity (required), product_id (read-only). A sample items value might be: [ {"order_product_id":16,"product_id": 0,"quantity":2} ]' + description: |- + The items in the shipment. This object has the following members, all integer: order_product_id (required), quantity (required), product_id (read-only). A sample items value might be: [ {"order_product_id":16,"product_id": 0,"quantity":2} ] type: array items: type: object @@ -3548,8 +3198,15 @@ components: type: integer example: 87 quantity: - type: number + type: integer example: 2 + shipping_provider_display_name: + type: string + description: The human-readable name for the `shipping_provider`. + readOnly: true + generated_tracking_link: + type: string + description: The tracking link that is generated using the combination of either the `tracking_number` and `shipping_provider` or `tracking_number` and `tracking_carrier`. This will be empty if the custom `tracking_link` value is provided. x-internal: false orderConsignments_Resource: title: orderConsignments_Resource @@ -3609,7 +3266,7 @@ components: example: 'https://api.bigcommerce.com/stores/{store_hash}/v2/orders/129/coupons' type: string resource: - description: resource of the coupons. + description: Resource of the coupons. readOnly: true example: /orders/129/coupons type: string @@ -3626,7 +3283,7 @@ components: example: total-coupon type: string amount: - description: 'Amount of the discount.(Float, Float-As-String, Integer) ' + description: Amount of the discount.(Float, Float-As-String, Integer) example: '1.2100' type: string name: @@ -3678,11 +3335,10 @@ components: example: S type: string value: - description: This value is used to access the Customer File Upload. - example: '70' + description: For file-upload type, itʼs a unique string describing the properties of the file upload. For other types, itʼs the value of the property. + example: "{\"originalName\":\"BigCommerceLogo.jpeg\",\"temporaryPath\":\"121_fbfb71dfc5a5d911f62d8e35dedd6e45.jpeg\",\"path\":\"f606efcae7e179970b19c3658142c5d0.jpeg\"}" type: string type: - type: string enum: - Checkbox - Date field @@ -3695,7 +3351,7 @@ components: example: Checkbox description: Option Type name: - description: 'The option’s name, as used internally. Must be unique.' + description: The option’s name, as used internally. Must be unique. example: Apparel sizes type: string display_style: @@ -3730,10 +3386,10 @@ components: description: The form field name. value: description: The form field value. - type: - - number - - string - - array + oneOf: + - type: number + - type: string + - type: array example: 123BAF items: type: string @@ -3846,7 +3502,6 @@ components: timestamp: type: string description: Time the order was created in RFC 2822 format. - format: date-time shipping_provider_id: type: string example: bcstatic @@ -3886,6 +3541,11 @@ components: description: Tracking number of the shipment. example: w4se4b6ASFEW4T maxLength: 50 + tracking_link: + type: string + description: The custom tracking link supplied on POST or PUT shipments. For the auto-generated tracking link see the `generated_tracking_link` property. + example: https://www.mycustomtrackinglink.com/tracking + maxLength: 500 shipping_method: description: | Additional information to describe the method of shipment (ex. Standard, Ship by Weight, Custom Shipment). Can be used for live quotes from certain shipping providers. @@ -3898,6 +3558,7 @@ components: enum: - auspost - canadapost + - carrier_{your_carrier_id} (only used if the carrier is a [third-party Shipping Provider](/docs/integrations/shipping)) - endicia - usps - fedex @@ -3916,7 +3577,8 @@ components: description: Comments the shipper wishes to add. maxLength: 65535 items: - description: 'The items in the shipment. This object has the following members, all integer: order_product_id (required), quantity (required), product_id (read-only). A sample items value might be: [ {"order_product_id":16,"product_id": 0,"quantity":2} ]' + description: |- + The items in the shipment. This object has the following members, all integer: order_product_id (required), quantity (required), product_id (read-only). A sample items value might be: [ {"order_product_id":16,"product_id": 0,"quantity":2} ] type: array items: type: object @@ -3925,7 +3587,7 @@ components: type: integer example: 5 quantity: - type: number + type: integer example: 2 orderShipment_Put: type: object @@ -3951,6 +3613,7 @@ components: enum: - auspost - canadapost + - carrier_{your_carrier_id} (only used if the carrier is a [third-party Shipping Provider](/docs/integrations/shipping)) - endicia - usps - fedex @@ -3964,6 +3627,11 @@ components: description: |- Tracking carrier for the shipment. Acceptable values for `tracking_carrier` include an empty string (`""`) or one of the valid [tracking-carrier values](https://github.com/bigcommerce/dev-docs/blob/master/assets/csv/tracking_carrier_values.csv). + tracking_link: + type: string + description: The custom tracking link supplied on POST or PUT shipments. For the auto-generated tracking link see the `generated_tracking_link` property. + example: https://www.mycustomtrackinglink.com/tracking + maxLength: 500 comments: type: string description: Comments the shipper wishes to add. @@ -3991,7 +3659,7 @@ components: type: string system_description: description: System description of the order status. - example: 'An incomplete order happens when a shopper reached the payment page, but did not complete the transaction.' + example: An incomplete order happens when a shopper reached the payment page, but did not complete the transaction. type: string x-internal: false ordersCountStatus: @@ -4017,11 +3685,11 @@ components: x-internal: false properties: base_handling_cost: - description: 'The value of the base handling cost. (Float, Float-As-String, Integer)' + description: The value of the base handling cost. (Float, Float-As-String, Integer) example: '0.0000' type: string base_shipping_cost: - description: 'The value of the base shipping cost. (Float, Float-As-String, Integer)' + description: The value of the base shipping cost. (Float, Float-As-String, Integer) example: '0.0000' type: string base_wrapping_cost: @@ -4037,34 +3705,33 @@ components: customer_id: type: number customer_message: - description: 'Message that the customer entered (number, options) -o the `Order Comments` box during checkout.' + description: Message that the customer entered (number, options) -o the `Order Comments` box during checkout. example: Thank you type: string date_created: - description: 'The date the order was created, formatted in the RFC-2822 standard. You set this attribute on Order creation (POST) to support the migration of historical orders. If you do not provide a value, then it will default to the current date/time. e.g., `Tue, 20 Nov 2012 00:00:00 +0000`.' + description: The date the order was created, formatted in the RFC-2822 standard. You set this attribute on Order creation (POST) to support the migration of historical orders. If you do not provide a value, then it will default to the current date/time. e.g., `Tue, 20 Nov 2012 00:00:00 +0000`. type: string default_currency_code: description: The currency code of the transactional currency the shopper pays in; writeable when multi-currency is enabled. type: string discount_amount: - description: 'Amount of discount for this transaction. (Float, Float-As-String, Integer)' + description: Amount of discount for this transaction. (Float, Float-As-String, Integer) example: '0.0000' type: string ebay_order_id: - description: 'If the order was placed through eBay, the eBay order number will be included. Otherwise, the value will be `0`.' + description: If the order was placed through eBay, the eBay order number will be included. Otherwise, the value will be `0`. example: '0' type: string external_id: - description: 'The order ID in another system, such as the Amazon Order ID if this is an Amazon order. After setting it, you cannot write to or update the `external_id`. You can update this field using a POST request, but a PUT request to update the order will return a 400 error. Please remove it from your request before trying again.' + description: (Read-only) The order ID in another system, such as the Amazon order ID if this is an Amazon order. example: null - oneOf: - - type: string + type: string nullable: true + readOnly: true external_merchant_id: - description: 'The merchant ID represents an upstream order from an external system. It is the source of truth for orders. After setting it, you cannot write to or update the `external_merchant_id`. For example, you can update the Facebook by Meta page ID in a POST request, but a PUT request to update the order will return a 400 error. Please remove it from your request before trying again.' + description: The merchant ID represents an upstream order from an external system. It is the source of truth for orders. After setting it, you cannot write to or update the `external_merchant_id`. For example, you can update the Facebook by Meta page ID in a POST request, but a PUT request to update the order will return a 400 error. Please remove it from your request before trying again. example: null - oneOf: - - type: string + type: string nullable: true external_source: description: |- @@ -4076,19 +3743,19 @@ components: type: string nullable: true geoip_country: - description: 'The full name of the country where the customer made the purchase, based on the IP.' + description: The full name of the country where the customer made the purchase, based on the IP. example: United States type: string geoip_country_iso2: - description: 'The country where the customer made the purchase, in ISO2 format, based on the IP.' + description: The country where the customer made the purchase, in ISO2 format, based on the IP. example: US type: string handling_cost_ex_tax: - description: 'The value of the handling cost, excluding tax. (Float, Float-As-String, Integer)' + description: The value of the handling cost, excluding tax. (Float, Float-As-String, Integer) example: '0.0000' type: string handling_cost_inc_tax: - description: 'The value of the handling cost, including tax. (Float, Float-As-String, Integer)' + description: The value of the handling cost, including tax. (Float, Float-As-String, Integer) example: '0.0000' type: string ip_address: @@ -4108,7 +3775,7 @@ components: example: '2001:db8:3333:4444:5555:6666:7777:8888' maxLength: 39 is_deleted: - description: 'Indicates whether the order was deleted (archived). Set to to true, to archive an order.' + description: Indicates whether the order was deleted (archived). Set to to true, to archive an order. example: false type: boolean items_shipped: @@ -4124,7 +3791,8 @@ components: example: false type: boolean payment_method: - description: 'The payment method for this order. Can be one of the following: `Manual`, `Credit Card`, `cash`, `Test Payment Gateway`, etc.' + description: |- + The payment method for this order. Can be one of the following: `Manual`, `Credit Card`, `cash`, `Test Payment Gateway`, etc. enum: - Credit Card - Cash @@ -4138,15 +3806,15 @@ components: - type: string - type: number refunded_amount: - description: 'The amount refunded from this transaction; always returns `0`. (Float, Float-As-String, Integer) ' + description: The amount refunded from this transaction; always returns `0`. (Float, Float-As-String, Integer) example: '0.0000' type: string shipping_cost_ex_tax: - description: 'The value of shipping cost, excluding tax. (Float, Float-As-String, Integer)' + description: The value of shipping cost, excluding tax. (Float, Float-As-String, Integer) example: '0.0000' type: string shipping_cost_inc_tax: - description: 'The value of shipping cost, including tax. (Float, Float-As-String, Integer)' + description: The value of shipping cost, including tax. (Float, Float-As-String, Integer) example: '0.0000' type: string staff_notes: @@ -4158,11 +3826,11 @@ components: description: The status ID of the order. type: integer subtotal_ex_tax: - description: 'Override value for subtotal excluding tax. If specified, the field `subtotal_inc_tax` is also required. (Float, Float-As-String, Integer)' + description: Override value for subtotal excluding tax. If specified, the field `subtotal_inc_tax` is also required. (Float, Float-As-String, Integer) example: '225.0000' type: string subtotal_inc_tax: - description: 'Override value for subtotal including tax. If specified, the field `subtotal_ex_tax` is also required. (Float, Float-As-String, Integer)' + description: Override value for subtotal including tax. If specified, the field `subtotal_ex_tax` is also required. (Float, Float-As-String, Integer) example: '225.0000' type: string tax_provider_id: @@ -4184,21 +3852,21 @@ components: external_order_id: type: string example: external-order-id - description: The external id of the order. + description: The order ID in another system, such as the Amazon Order ID if this is an Amazon order. After setting it, you can update this field using a POST or PUT request. total_ex_tax: - description: 'Override value for the total, excluding tax. If specified, the field `total_inc_tax` is also required. (Float, Float-As-String, Integer)' + description: Override value for the total, excluding tax. If specified, the field `total_inc_tax` is also required. (Float, Float-As-String, Integer) example: '225.0000' type: string total_inc_tax: - description: 'Override value for the total, including tax. If specified, the field `total_ex_tax` is also required. (Float, Float-As-String, Integer)' + description: Override value for the total, including tax. If specified, the field `total_ex_tax` is also required. (Float, Float-As-String, Integer) example: '225.0000' type: string wrapping_cost_ex_tax: - description: 'The value of the wrapping cost, excluding tax. (Float, Float-As-String, Integer)' + description: The value of the wrapping cost, excluding tax. (Float, Float-As-String, Integer) example: '0.0000' type: string wrapping_cost_inc_tax: - description: 'The value of the wrapping cost, including tax. (Float, Float-As-String, Integer)' + description: The value of the wrapping cost, including tax. (Float, Float-As-String, Integer) example: '0.0000' type: string billingAddress_Base: @@ -4271,7 +3939,7 @@ components: zip: type: string example: '12345' - description: 'Zip or postal code, as a string.' + description: Zip or postal code, as a string. country: type: string example: United States @@ -4307,39 +3975,46 @@ components: type: string description: A read-only value representing the date of shipment. Do not attempt to modify or set this value in a POST or PUT request. RFC-2822 cart_id: - description: 'The cart ID from which this order originated, if applicable. Correlates with the Cart API. This is a read-only field; do not set or modify its value in a POST or PUT request.' + description: The cart ID from which this order originated, if applicable. Correlates with the Cart API. This is a read-only field; do not set or modify its value in a POST or PUT request. example: a8458391-ef68-4fe5-9ec1-442e6a767364 type: string status: type: string - description: 'The status will include one of the (string, options) - values defined under Order Statuses. This value is read-only. Do not attempt to modify or set this value in a POST or PUT operation.' + description: The status will include one of the (string, options) - values defined under Order Statuses. This value is read-only. Do not attempt to modify or set this value in a POST or PUT operation. example: Awaiting Fulfillment subtotal_tax: - description: 'A read-only value. Do not attempt to set or modify this value in a POST or PUT request. (Float, Float-As-String, Integer)' + description: A read-only value. Do not attempt to set or modify this value in a POST or PUT request. (Float, Float-As-String, Integer) example: '0.0000' type: string shipping_cost_tax: - description: 'A read-only value. Do not attempt to modify or set this value in a POST or PUT request. (Float, Float-As-String, Integer)' + description: A read-only value. Do not attempt to modify or set this value in a POST or PUT request. (Float, Float-As-String, Integer) example: '0.0000' type: string shipping_cost_tax_class_id: - description: 'Shipping-cost tax class. A read-only value. Do not attempt to modify or set this value in a POST or PUT request. (NOTE: Value ignored if automatic tax is enabled on the store.)' + description: |- + Shipping-cost tax class. A read-only value. Do not attempt to modify or set this value in a POST or PUT request. (NOTE: Value ignored if automatic tax is enabled on the store.) example: 2 type: integer handling_cost_tax: - description: 'A read-only value. Do not attempt to modify or set this value in a POST or PUT request. (Float, Float-As-String, Integer)' + description: A read-only value. Do not attempt to modify or set this value in a POST or PUT request. (Float, Float-As-String, Integer) example: '0.0000' type: string handling_cost_tax_class_id: - description: 'A read-only value. Do not attempt to set or modify this value in a POST or PUT request. (NOTE: Value ignored if automatic tax is enabled on the store.)' + description: |- + A read-only value. Do not attempt to set or modify this value in a POST or PUT request. + + (NOTE: Value ignored if automatic tax is enabled on the store.) example: 2 type: integer wrapping_cost_tax: - description: 'A read-only value. Do not attempt to modify or set this value in a POST or PUT request. (Float, Float-As-String, Integer)' + description: A read-only value. Do not attempt to modify or set this value in a POST or PUT request. (Float, Float-As-String, Integer) example: '0.0000' type: string wrapping_cost_tax_class_id: - description: 'A read-only value. Do not attempt to set or modify this value in a POST or PUT request. (NOTE: Value ignored if automatic tax is enabled on the store.)' + description: |- + A read-only value. Do not attempt to set or modify this value in a POST or PUT request. + + NOTE: Value ignored if automatic tax is enabled on the store. example: 3 type: integer payment_status: @@ -4358,23 +4033,23 @@ components: - void - void pending store_credit_amount: - description: 'Represents the store credit that the shopper has redeemed on this individual order. This is a read-only value. Do not pass in a POST or PUT request. (Float, Float-As-String, Integer)' + description: Represents the store credit that the shopper has redeemed on this individual order. This is a read-only value. Do not pass in a POST or PUT request. (Float, Float-As-String, Integer) example: '0.0000' type: string gift_certificate_amount: - description: 'A read-only value. Do not pass in a POST or PUT request. (Float, Float-As-String, Integer)' + description: A read-only value. Do not pass in a POST or PUT request. (Float, Float-As-String, Integer) example: '0.0000' type: string currency_id: - description: 'The display currency ID. Depending on the currency selected, the value can be different from the transactional currency. A read-only value. Do not pass in a POST or PUT request. In v2 display currency is set to the transactional currency, ''default_currency_id''.' + description: The display currency ID. Depending on the currency selected, the value can be different from the transactional currency. A read-only value. Do not pass in a POST or PUT request. In v2 display currency is set to the transactional currency, ''default_currency_id''. example: 1 type: integer currency_code: - description: 'The currency code of the display currency used to present prices to the shopper on the storefront. Depending on the currency selected, the value can be different from the transactional currency. A read-only value. Do not pass in a POST or PUT request.' + description: The currency code of the display currency used to present prices to the shopper on the storefront. Depending on the currency selected, the value can be different from the transactional currency. A read-only value. Do not pass in a POST or PUT request. example: USD type: string currency_exchange_rate: - description: 'The exchange rate between the store’s default currency and the display currency. A read-only value. Do not pass in a POST or PUT request. For orders created using the V2 endpoints, this value is always 1 (only in the storefront this value can be different to 1). (Float, Float-As-String, Integer)' + description: The exchange rate between the store’s default currency and the display currency. A read-only value. Do not pass in a POST or PUT request. For orders created using the V2 endpoints, this value is always 1 (only in the storefront this value can be different to 1). (Float, Float-As-String, Integer) example: '1.0000000000' type: string default_currency_id: @@ -4386,15 +4061,15 @@ components: example: EUR type: string store_default_currency_code: - description: The currency code of the store's default currency. + description: The currency code of the storeʼs default currency. example: USD type: string store_default_to_transactional_exchange_rate: - description: The exchange rate between the store's default currency and the transactional currency used in the order. + description: The exchange rate between the storeʼs default currency and the transactional currency used in the order. example: '100.0000000000' type: string coupon_discount: - description: 'A read-only value. Do not pass in a POST or PUT request. (Float, Float-As-String, Integer)' + description: A read-only value. Do not pass in a POST or PUT request. (Float, Float-As-String, Integer) example: '5.0000' type: string shipping_address_count: @@ -4405,8 +4080,8 @@ components: example: false type: boolean order_source: - description: Orders submitted from the store’s website will include a `www` value. Orders submitted with the API will be set to `external`. This value is read-only. Do not pass in a POST or PUT. - example: www + description: Orders submitted from the storeʼs website will include a `www` value. Orders submitted with the Checkout API will be set to `checkout_api`. + example: www, iPhone, Android, mobile, manual type: string consignments: $ref: '#/components/schemas/orderConsignments_Resource' @@ -4429,8 +4104,8 @@ components: $ref: '#/components/schemas/formFields' orderCustomProduct_Put: type: object - title: orderCustomProduct_Put - description: | + title: Custom product + description: |- **Usage notes:** To `add` a custom product to an existing order, don't include `id` in the payload. You must provide a non-empty value for at least one of these fields: `name`, `name_customer`, or `name_merchant`. @@ -4459,7 +4134,7 @@ components: example: Towel Type 1 description: The product name that is shown to merchant in control panel. quantity: - type: number + type: integer price_ex_tax: type: number price_inc_tax: @@ -4478,7 +4153,7 @@ components: - price_inc_tax x-internal: false orderCatalogProduct_Put: - title: orderCatalogProduct_Put + title: Catalog product description: | **Usage notes** @@ -4498,9 +4173,45 @@ components: properties: id: type: integer - description: 'The order product `id`. To add a product to an existing order, donʼt include `id` in the payload. `id` is required when updating an order product.' + description: The order product `id`. To add a product to an existing order, donʼt include `id` in the payload. `id` is required when updating an order product. - $ref: '#/components/schemas/orderCatalogProduct_Post' x-internal: false + orderRemoveProduct_Put: + title: Remove Product from Order + type: object + properties: + id: + type: integer + description: |- + The `id` returned from a request to the [List order products](/docs/rest-management/orders/order-products#list-order-products) or the [Get an order product](/docs/rest-management/orders/order-products#get-an-order-product) endpoint. + example: 123 + product_id: + type: integer + description: The numeric ID of the product. + example: 117 + quantity: + type: integer + description: The quantity of product being removed. + example: 1 + product_options: + type: array + description: List of product variant options and modifiers. `product_options` are required when removing a product with variants and not specifying the `variant_id`, or when products have mandatory modifiers. + items: + type: object + properties: + cost_price_inc_tax: + type: string + description: |- + The product’s cost price including tax. (Float, Float-As-String, Integer) + The cost of your products to you; this is never shown to customers, but can be used for accounting purposes. + example: '50.0000' + price_ex_tax: + type: string + description: |- + The products cost price excluding tax. (Float, Float-As-String, Integer) + The cost of your products to you; this is never shown to customers, but can be used for accounting purposes. Read Only. + readOnly: true + example: '0.0000' orderCatalogProduct_Post: title: orderCatalogProduct_Post description: | @@ -4515,13 +4226,13 @@ components: type: integer name: type: string - description: 'Alias for `name_customer`. The product name that is shown to customer in storefront. `xxx` and `xxx_customer` always hold the same value, updating either `xxx` or `xxx_customer` will change value for both of those fields.' + description: Alias for `name_customer`. The product name that is shown to customer in storefront. `xxx` and `xxx_customer` always hold the same value, updating either `xxx` or `xxx_customer` will change value for both of those fields. example: Fog Linen Chambray Towel - Beige Stripe minLength: 1 name_customer: type: string example: Fog Linen Chambray Towel - Beige Stripe - description: 'The product name that is shown to customer in storefront. `xxx` and `xxx_customer` always hold the same value, updating either `xxx` or `xxx_customer` will change value for both of those fields.' + description: The product name that is shown to customer in storefront. `xxx` and `xxx_customer` always hold the same value, updating either `xxx` or `xxx_customer` will change value for both of those fields. minLength: 1 name_merchant: type: string @@ -4529,13 +4240,13 @@ components: description: The product name that is shown to merchant in control panel. product_options: type: array - description: 'List of product variant options and modifiers. `product_options` are required when adding a product with variants and not specifying the `variant_id`, or when products have mandatory modifiers.' + description: List of product variant options and modifiers. `product_options` are required when adding a product with variants and not specifying the `variant_id`, or when products have mandatory modifiers. items: type: object properties: id: type: integer - description: 'Numeric ID of an option applied to the product from a list of options available to the product. This field has the same value as `product_option_id` when [retrieving products in an order](/docs/rest-management/orders/order-products#list-order-products).' + description: Numeric ID of an option applied to the product from a list of options available to the product. This field has the same value as `product_option_id` when [retrieving products in an order](/docs/rest-management/orders/order-products#list-order-products). value: type: string description: |- @@ -4552,11 +4263,11 @@ components: display_name: type: string example: couleur - description: 'Alias for display_name_customer. The product option name that is shown to customer in storefront. `xxx` and `xxx_customer` always hold the same value, updating either `xxx` or `xxx_customer` will change value for both of those fields.' + description: Alias for display_name_customer. The product option name that is shown to customer in storefront. `xxx` and `xxx_customer` always hold the same value, updating either `xxx` or `xxx_customer` will change value for both of those fields. minLength: 1 display_name_customer: type: string - description: 'The product option name that is shown to customer in storefront. `xxx` and `xxx_customer` always hold the same value, updating either `xxx` or `xxx_customer` will change value for both of those fields.' + description: The product option name that is shown to customer in storefront. `xxx` and `xxx_customer` always hold the same value, updating either `xxx` or `xxx_customer` will change value for both of those fields. example: couleur minLength: 1 display_name_merchant: @@ -4566,7 +4277,7 @@ components: display_value: type: string example: bleu - description: 'Alias for display_value_customer. The product option value that is shown to customer in storefront. `xxx` and `xxx_customer` always hold the same value, updating either `xxx` or `xxx_customer` will change value for both of those fields.' + description: Alias for display_value_customer. The product option value that is shown to customer in storefront. `xxx` and `xxx_customer` always hold the same value, updating either `xxx` or `xxx_customer` will change value for both of those fields. minLength: 1 display_value_merchant: type: string @@ -4576,10 +4287,10 @@ components: display_value_customer: type: string example: bleu - description: 'The product option value that is shown to a customer in storefront.`xxx` and `xxx_customer` always hold the same value, updating either `xxx` or `xxx_customer` will change value for both of those fields.' + description: The product option value that is shown to a customer in storefront.`xxx` and `xxx_customer` always hold the same value, updating either `xxx` or `xxx_customer` will change value for both of those fields. minLength: 1 quantity: - type: number + type: integer price_inc_tax: type: number price_ex_tax: @@ -4591,18 +4302,18 @@ components: description: '""' wrapping_id: type: integer - description: 'ID of the gift wrapping that will be used for this product. If provided, then `wrapping_cost_ex_tax` and `wrapping_cost_inc_tax` are required. When updating an order product line item, if `wrapping_id` is set to `0` and no other wrapping fields are provided,then the wrapping will be removed from the order product.' + description: ID of the gift wrapping that will be used for this product. If provided, then `wrapping_cost_ex_tax` and `wrapping_cost_inc_tax` are required. When updating an order product line item, if `wrapping_id` is set to `0` and no other wrapping fields are provided,then the wrapping will be removed from the order product. wrapping_name: type: string - description: 'If the `wrapping_id` is provided, this field will populate with the name of the gift wrapping that is to be used.' + description: If the `wrapping_id` is provided, this field will populate with the name of the gift wrapping that is to be used. wrapping_message: type: string wrapping_cost_ex_tax: type: number - description: 'When provided, this value should be equal to `wrapping_cost_ex_tax` times quantity to accurately reflect wrapping cost per unit.' + description: When provided, this value should be equal to `wrapping_cost_ex_tax` times quantity to accurately reflect wrapping cost per unit. wrapping_cost_inc_tax: type: number - description: 'When provided, this value should be equal to `wrapping_cost_inc_tax` times quantity to accurately reflect wrapping cost per unit.' + description: When provided, this value should be equal to `wrapping_cost_inc_tax` times quantity to accurately reflect wrapping cost per unit. x-internal: false orderCustomProduct_Post: title: orderCustomProduct_Post @@ -4625,6 +4336,8 @@ components: type: string example: Fog Linen Chambray Towel - Beige Stripe description: Alias for name_customer. The product name that is shown to customer in storefront. + minLength: 1 + maxLength: 250 name_customer: type: string example: Fog Linen Chambray Towel - Beige Stripe @@ -4634,7 +4347,7 @@ components: example: Towel Type 1 description: The product name that is shown to merchant in control panel. quantity: - type: number + type: integer price_inc_tax: type: number price_ex_tax: @@ -4651,29 +4364,206 @@ components: x-internal: false order_Put: allOf: - - $ref: '#/components/schemas/order_Shared' - type: object properties: + base_handling_cost: + description: The value of the base handling cost. (Float, Float-As-String, Integer) + example: '0.0000' + type: string + base_shipping_cost: + description: The value of the base shipping cost. (Float, Float-As-String, Integer) + example: '0.0000' + type: string + base_wrapping_cost: + description: The value of the base wrapping cost expressed as a floating point number to four decimal places in string format. + example: '0.0000' + type: string billing_address: $ref: '#/components/schemas/billingAddress_Put' + channel_id: + description: Shows where the order originated. The channel_id will default to 1. + example: 1 + type: integer consignments: $ref: '#/components/schemas/orderConsignment_Put' + customer_id: + type: number + customer_message: + description: Message that the customer entered (number, options) -o the `Order Comments` box during checkout. + example: Thank you + type: string + date_created: + description: The date the order was created, formatted in the RFC-2822 standard. You set this attribute on Order creation (POST) to support the migration of historical orders. If you do not provide a value, then it will default to the current date/time. e.g., `Tue, 20 Nov 2012 00:00:00 +0000`. + type: string + default_currency_code: + description: A read-only field displays the currency code of the [transactional currency](/docs/store-operations/currencies#display-vs-transactional) the shopper uses. + type: string + readOnly: true + discount_amount: + description: Amount of discount for this transaction. (Float, Float-As-String, Integer) + example: '0.0000' + type: string + ebay_order_id: + description: If the order was placed through eBay, the eBay order number will be included. Otherwise, the value will be `0`. + example: '0' + type: string + external_id: + description: (Read-only) The order ID in another system, such as the Amazon Order ID if this is an Amazon order. + example: null + type: string + nullable: true + readOnly: true + external_merchant_id: + description: The merchant ID represents an upstream order from an external system. It is the source of truth for orders. After setting it, you cannot write to or update the `external_merchant_id`. For example, you can update the Facebook by Meta page ID in a POST request, but a PUT request to update the order will return a 400 error. Please remove it from your request before trying again. + example: null + type: string + nullable: true + external_source: + description: |- + This value identifies an external system that generated the order and submitted it to BigCommerce with the Orders API. + * When supplying the value, we recommend combining the type of system and vendor, e.g., ERP (Acumatica) or POS (Square). + * If you are migrating historical orders processed on another eCommerce platform to BigCommerce, supply the following code as the value: M-MIG. This code will exclude historical orders from the store’s GMV/order count, which factors into pricing. + * If you do not provide a value, then it will default to null. + example: null + type: string + nullable: true + geoip_country: + description: The full name of the country where the customer made the purchase, based on the IP. + example: United States + type: string + geoip_country_iso2: + description: The country where the customer made the purchase, in ISO2 format, based on the IP. + example: US + type: string + handling_cost_ex_tax: + description: The value of the handling cost, excluding tax. (Float, Float-As-String, Integer) + example: '0.0000' + type: string + handling_cost_inc_tax: + description: The value of the handling cost, including tax. (Float, Float-As-String, Integer) + example: '0.0000' + type: string + ip_address: + type: string + description: |- + IPv4 Address of the customer, if known. + + Note: You can set either `ip_address` or `ip_address_v6`. Setting the `ip_address` value will reset the `ip_address_v6` value and vice versa. + example: 12.345.678.910 + maxLength: 30 + ip_address_v6: + type: string + description: |- + IPv6 Address of the customer, if known. + + Note: You can set either `ip_address` or `ip_address_v6`. Setting the `ip_address_v6` value will reset the `ip_address` value and vice versa. + example: '2001:db8:3333:4444:5555:6666:7777:8888' + maxLength: 39 + is_deleted: + description: Indicates whether the order was deleted (archived). Set to to true, to archive an order. + example: false + type: boolean + items_shipped: + description: The number of items that have been shipped. + example: 0 + type: number + items_total: + description: The total number of items in the order. + example: 1 + type: number + order_is_digital: + description: Whether this is an order for digital products. + example: false + type: boolean payment_method: type: string description: 'The payment method for this order. Can be one of the following: `Manual`, `Credit Card`, `Cash`,`Test Payment Gateway`, etc.' + payment_provider_id: + description: The external Transaction ID/Payment ID within this order’s payment provider (if a payment provider was used). + oneOf: + - type: string + - type: number products: type: array items: anyOf: - $ref: '#/components/schemas/orderCatalogProduct_Put' - $ref: '#/components/schemas/orderCustomProduct_Put' + - $ref: '#/components/schemas/orderRemoveProduct_Put' + refunded_amount: + description: The amount refunded from this transaction; always returns `0`. (Float, Float-As-String, Integer) + example: '0.0000' + type: string + shipping_cost_ex_tax: + description: The value of shipping cost, excluding tax. (Float, Float-As-String, Integer) + example: '0.0000' + type: string + shipping_cost_inc_tax: + description: The value of shipping cost, including tax. (Float, Float-As-String, Integer) + example: '0.0000' + type: string + staff_notes: + type: string + description: Any additional notes for staff. + example: Send Saturday + maxLength: 65535 shipping_addresses: - allOf: - - type: object - properties: - id: - type: integer - - $ref: '#/components/schemas/shippingAddress_Put' + type: array + items: + allOf: + - type: object + properties: + id: + type: integer + - $ref: '#/components/schemas/shippingAddress_Put' + status_id: + description: The status ID of the order. + type: integer + subtotal_ex_tax: + description: 'Override value for subtotal excluding tax. If specified, the field `subtotal_inc_tax` is also required. (Float, Float-As-String, Integer)' + example: '225.0000' + type: string + subtotal_inc_tax: + description: 'Override value for subtotal including tax. If specified, the field `subtotal_ex_tax` is also required. (Float, Float-As-String, Integer)' + example: '225.0000' + type: string + tax_provider_id: + description: | + BasicTaxProvider - Tax is set to manual and order is created in the store. + + AvaTaxProvider - Tax is set to automatic and order is created in the store. Used for Avalara. + + "" (empty string) - The order is created with the API, or the tax provider is unknown. + enum: + - BasicTaxProvider + - AvaTaxProvider + - '' + type: string + customer_locale: + type: string + example: en + description: The customer’s locale. + external_order_id: + type: string + nullable: true + example: external-order-id + description: The order ID in another system, such as the Amazon Order ID if this is an Amazon order. After setting it, you can update this field using a POST or PUT request. + total_ex_tax: + description: Override value for the total, excluding tax. If specified, the field `total_inc_tax` is also required. (Float, Float-As-String, Integer) + example: '225.0000' + type: string + total_inc_tax: + description: Override value for the total, including tax. If specified, the field `total_ex_tax` is also required. (Float, Float-As-String, Integer) + example: '225.0000' + type: string + wrapping_cost_ex_tax: + description: The value of the wrapping cost, excluding tax. (Float, Float-As-String, Integer) + example: '0.0000' + type: string + wrapping_cost_inc_tax: + description: The value of the wrapping cost, including tax. (Float, Float-As-String, Integer) + example: '0.0000' + type: string order_Post: title: order_Post description: Products and Billing address only required for POST operation. @@ -4881,12 +4771,12 @@ components: description: 2-letter ISO Alpha-2 code for the country. email: type: string - description: Pickup location's email address. + description: Pickup locationʼs email address. maxLength: 255 example: location1@example.com phone: type: string - description: Pickup location's phone number. + description: Pickup locationʼs phone number. maxLength: 125 example: +1 111-111-1111 x-examples: {} @@ -4912,7 +4802,7 @@ components: address_line_2: Suite 101 city: Austin state: Texas - postal_code: '78726' + postal_code: 78726 country_alpha2: US email: location1@example.com phone: +1 111-111-1111 @@ -5258,11 +5148,11 @@ components: example: 4.1 handling_cost_ex_tax: type: number - description: 'The handling charge, excluding tax.' + description: The handling charge, excluding tax. example: 4.1 handling_cost_inc_tax: type: number - description: 'The handling charge, including tax.' + description: The handling charge, including tax. example: 5.3 handling_cost_tax: type: number @@ -5294,7 +5184,7 @@ components: zip: '12345' country: United States country_iso2: US - phone: '0410999888' + phone: 0410999888 email: janedoe@example.com form_fields: - name: License Id @@ -5346,7 +5236,7 @@ components: zip: type: string example: '12345' - description: 'Zip or postal code, as a string.' + description: Zip or postal code, as a string. country: type: string example: United States diff --git a/reference/orders.v3.yml b/reference/orders.v3.yml index d790e4fb9..bff39ebe4 100644 --- a/reference/orders.v3.yml +++ b/reference/orders.v3.yml @@ -27,7 +27,7 @@ tags: paths: '/orders/{order_id}/payment_actions/capture': post: - summary: Capture + summary: Capture order payment description: |- Capture the payment for an order. When there are no payment method validation issues, the capture process is successful, the `payment_status` updates to `capture pending`, and the payment request is scheduled. The payment request itself occurs asynchronously. Requires at least one of the following scopes: @@ -161,6 +161,10 @@ paths: Requires at least one of the following scopes: * `store_v2_orders` * `store_v2_transactions` + + **Note:** + Order refunds are processed consecutively. Processing synchronous refunds on an order are not yet supported. + operationId: postrefundquote parameters: - $ref: '#/components/parameters/ContentType' @@ -169,6 +173,14 @@ paths: application/json: schema: $ref: '#/components/schemas/RefundQuote_Post' + application/xml: + schema: + type: object + properties: {} + multipart/form-data: + schema: + type: object + properties: {} required: true x-examples: Quantity: @@ -186,7 +198,7 @@ paths: - item_type: ORDER item_id: 1234 amount: 1 - reason: Overchaged $1.00 + reason: Overcharged $1.00 Multiple Items: items: - item_id: 75 @@ -195,6 +207,7 @@ paths: - item_id: 79 item_type: SHIPPING amount: 10 + description: '' responses: '201': $ref: '#/components/responses/RefundQuote_Resp' @@ -214,6 +227,10 @@ paths: Requires at least one of the following scopes: * `store_v2_orders` * `store_v2_transactions` + + **Note:** + Order refunds are processed consecutively. Processing synchronous refunds on an order are not yet supported. + operationId: postrefund parameters: - $ref: '#/components/parameters/ContentType' @@ -226,28 +243,18 @@ paths: x-examples: Quantity: items: - - item_id: 75 - item_type: PRODUCT + - item_type: PRODUCT + item_id: 31 + amount: 35.00 quantity: 1 + reason: Not the right product. payments: - provider_id: storecredit - amount: 232.75 + amount: 37.89 offline: false - Amount: - order_id: 1 - items: - - item_type: SHIPPING - item_id: 1 - amount: 1.99 - reason: string - reason: Wrong t-shirt size - payments: - - |- - { - "provider_id": "checkout_paypalexpress", - "amount": 9.99, - "offline": true - } + merchant_calculated_override: + - total_amount: 45.00 + total_tax: Tax Exempt (Order Level): order_id: 1234 items: @@ -384,6 +391,8 @@ paths: * `store_v2_orders_read_only` * `store_v2_orders` operationId: getrefunds + tags: + - Payment Actions parameters: - name: 'order_id:in' in: query @@ -420,7 +429,6 @@ paths: description: |- Filter results so they are earlier than or equal to provided date. - Must be in url-encoded RFC 3339 format. e.g. `2020-01-15T01:02:34-01:00` is RFC 3339 format. Url-encoded this will be `2020-01-15T01%3A02%3A34%2B01%3A00` @@ -440,8 +448,119 @@ paths: responses: '200': $ref: '#/components/responses/RefundCollection_Resp' + '/orders/payment_actions/refund_quotes': + post: + summary: Create Refund Quotes - BATCH + description: |- + Calculate the tax amount, total refund amount and get available payment options for an order refund by providing items and costs or quantities to refund. + + This endpoint will accept a batch of one or more. + + Requires at least one of the following scopes: + * `store_v2_orders` + * `store_v2_transactions` + operationId: postrefundquotes + parameters: + - $ref: '#/components/parameters/Accept' + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PostRefundQuotesRequest' + required: true + x-examples: + application/json: + - items: + - item_id: 76 + item_type: PRODUCT + quantity: 1 + tax_adjustment_amount: 0 + responses: + '201': + $ref: '#/components/responses/RefundQuotesBATCH_Resp' + '422': + description: Partial success/failure response. Status to roll up to the most severe individual failure to the whole request. + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/RefundQuote_Full' + errors: + type: array + items: + $ref: '#/components/schemas/FailedQuoteError' + meta: + $ref: '#/components/schemas/Meta' + Example 1: + examples: + response: + value: |- + { + "data": [ + { + "order_id": 1, + "total_refund_amount": 1.99, + "total_refund_tax_amount": 1.95, + "rounding": 1, + "adjustment": 0.05, + "tax_inclusive": true, + "refund_methods": [ + "" + ] + } + ], + "errors": [ + { + "order_id": 1, + "status": 422, + "error": "Refund amount is greater than remaining amount" + } + ], + "meta": { + "failure": 1, + "success": 1, + "total": 2 + } + } + '503': + description: Every request in the batch failed. The error object describes the failure for each component request. + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/RefundQuote_Full' + errors: + type: array + items: + $ref: '#/components/schemas/FailedQuoteError' + meta: + $ref: '#/components/schemas/Meta' + examples: + response: + value: + data: [] + errors: + - order_id: 1 + status: 503 + error: Tax service could not be contacted + - order_id: 100 + status: 422 + error: Refund amount exceeds remaining amount + meta: + failure: 2 + success: 0 + total: 2 tags: - Payment Actions + x-private: true '/orders/{order_id}/metafields': parameters: - $ref: '#/components/parameters/Accept' @@ -453,7 +572,7 @@ paths: description: | Gets a `Metafield` object list, by `order_id`. - The maxiumum number of metafields allowed on each order, product, category, variant, or brand is 250 per client ID. + The maximum number of metafields allowed on each order, product, category, variant, or brand is 250 per client ID. operationId: getOrderMetafieldsByOrderId parameters: - $ref: '#/components/parameters/PageParam' @@ -490,7 +609,7 @@ paths: description: |- Creates an order `Metafield`. - The maxiumum number of metafields allowed on each order, product, category, variant, or brand is 250 per client ID. + The maximum number of metafields allowed on each order, product, category, variant, or brand is 250 per client ID. operationId: createOrderMetafield parameters: - $ref: '#/components/parameters/ContentType' @@ -513,7 +632,7 @@ paths: $ref: '#/components/schemas/MetafieldResponse' '409': description: | - The `Metafield` conflicts with another `Metafield`. This can be the result of duplicate unique key combinations of the app's client id, namespace, key, resource_type, and resource_id. + The `Metafield` conflicts with another `Metafield`. This can be the result of duplicate unique key combinations of the app's client ID, namespace, key, resource_type, and resource_id. content: application/json: schema: @@ -704,7 +823,7 @@ paths: description: |- Updates order settings for a specific channel. - **Note:** You must override both notifications `email_addresses` or neither, i.e. either both notification `email_addresses` are an array of valid email addresses, or both `email_addresses` must be null. You may not have one set to an array of addesses and the other set to `null`. + **Note:** You must override both notifications `email_addresses` or neither, i.e. either both notification `email_addresses` are an array of valid email addresses, or both `email_addresses` must be null. You may not have one set to an array of addresses and the other set to `null`. operationId: UpdateChannelOrderSettings parameters: - $ref: '#/components/parameters/ContentType' @@ -776,10 +895,10 @@ components: format: int64 label: type: string - description: A description of the reason + description: A description of the reason. is_archived: type: boolean - description: Indicates whether or not the reason has been archived + description: Indicates whether or not the reason has been archived. x-internal: false PreferredOutcome: type: object @@ -789,10 +908,10 @@ components: format: int64 label: type: string - description: A description of the outcome + description: A description of the outcome. is_archived: type: boolean - description: Indicates whether or not the outcome has been archived + description: Indicates whether or not the outcome has been archived. x-internal: false CreateReturnRequest: type: object @@ -800,12 +919,12 @@ components: - items properties: items: - description: A collection of items to be returned + description: A collection of items to be returned. type: array items: $ref: '#/components/schemas/CreateReturnRequestItem' comment: - description: A comment provided to the merchant for review + description: A comment provided to the merchant for review. type: string title: CreateReturnRequest x-internal: false @@ -833,7 +952,7 @@ components: $ref: '#/components/schemas/Return_Full' Return_Full: type: object - description: A view of a return + description: A view of a return. properties: items: type: array @@ -842,11 +961,11 @@ components: total: type: string format: decimal - description: The total price of the items being returned + description: The total price of the items being returned. currency: type: string format: iso-4217 - description: The transactional currency of the return and the associated order + description: The transactional currency of the return and the associated order. customer: type: object properties: @@ -858,7 +977,7 @@ components: format: email comment: type: string - description: A comment provided to the merchant for review + description: A comment provided to the merchant for review. status: $ref: '#/components/schemas/Status_Full' date_modified: @@ -867,62 +986,62 @@ components: x-internal: false ReturnItem: type: object - description: A view of a return item + description: A view of a returned item. properties: id: type: integer format: int64 - description: The unique identifier of this return item + description: The unique identifier of this returned item. reference_id: $ref: '#/components/schemas/ItemReferenceId' quantity: type: integer - description: The quantity of items for which a return was requested + description: The quantity of items for which a return was requested. total: type: string format: decimal - description: The total price of the line item + description: The total price of the line item. preferred_outcome: type: object properties: id: type: integer format: int64 - description: Unique identifier of the preferred outcome + description: Unique identifier of the preferred outcome. label: type: string - description: A displayable label for the preferred outcome + description: A displayable label for the preferred outcome. reason: type: object properties: id: type: integer format: int64 - description: Unique identifier of the reason + description: Unique identifier of the reason. label: type: string - description: A displayable label for the reason + description: A displayable label for the reason. received_state: type: object properties: received_quantity: type: integer - description: The quantity of items marked as received by the merchant + description: The quantity of items marked as received by the merchant. pending_quantity: type: integer - description: The quantity of items pending receipt by the merchant + description: The quantity of items pending receipt by the merchant. review_state: type: object properties: approved_quantity: type: integer - description: The quantity of items approved for return by the merchant + description: The quantity of items approved for return by the merchant. pending_quantity: type: integer - description: The quantity of items pending receipt by the merchant + description: The quantity of items pending receipt by the merchant. rejected_quantity: type: integer - description: The quantity of items rejected by the merchant + description: The quantity of items rejected by the merchant. x-internal: false StatusUpdate_Full: type: object @@ -930,7 +1049,7 @@ components: return_id: type: integer format: int64 - description: The ID of the return for which the status should be updated + description: The ID of the return for which the status should be updated. new_status: $ref: '#/components/schemas/Status_Full' title: StatusUpdate_Full @@ -958,7 +1077,7 @@ components: id: type: integer format: int64 - description: The ID of the return for which the status was updated + description: The ID of the return for which the status was updated. status: $ref: '#/components/schemas/Status_Full' x-internal: false @@ -967,27 +1086,27 @@ components: properties: status: type: integer - description: Status code of the problem + description: Status code of the problem. title: type: string - description: A short description of the problem + description: A short description of the problem. type: type: string format: url - description: A resource describing the problem + description: A resource describing the problem. x-internal: false BatchOperationMeta: type: object properties: total: type: integer - description: The total number of operations in the batch + description: The total number of operations in the batch. success: type: integer - description: The number of failed operations in the batch + description: The number of failed operations in the batch. failed: type: integer - description: The number of failed operations in the batch + description: The number of failed operations in the batch. x-internal: false Pagination: type: object @@ -1050,13 +1169,13 @@ components: item_id: type: integer format: int64 - description: The ID of the item for which to update the received state + description: The item ID for updating the received state. received_quantity: type: integer - description: The quantity of items to be marked as received + description: The quantity of items to be marked as received. pending_quantity: type: integer - description: The quantity of items to be marked as pending + description: The quantity of items to be marked as pending. title: ReceivedItems_Put x-internal: false ReceivedItems_Base: @@ -1067,15 +1186,15 @@ components: item_id: type: integer format: int64 - description: The ID of the item for which received item status was updated + description: The ID of the item for which received item status was updated. received_quantity: type: integer format: int64 - description: The quantity of items marked as received + description: The quantity of items marked as received. pending_quantity: type: integer format: int64 - description: The quantity of items marked as pending + description: The quantity of items marked as pending. title: ReceivedItems_Base x-internal: false ReviewedItems_Put: @@ -1091,16 +1210,16 @@ components: item_id: type: integer format: int64 - description: The ID of the item for which to update the reviewed state + description: The item ID for updating the reviewed state. authorized_quantity: type: integer - description: The quantity of items to be marked as authorized + description: The quantity of items to be marked as authorized. rejected_quantity: type: integer - description: The quantity of items to be marked as rejected + description: The quantity of items to be marked as rejected. pending_quantity: type: integer - description: The quantity of items to be marked as pending + description: The quantity of items to be marked as pending. title: ReviewedItems_Put x-internal: false ReviewedItems_Base: @@ -1111,19 +1230,19 @@ components: item_id: type: integer format: int64 - description: The ID of the item for which reviewed status was updated + description: The ID of the item for which reviewed status was updated. authorized_quantity: type: integer format: int64 - description: The quantity of items marked as authorized + description: The quantity of items marked as authorized. rejected_quantity: type: integer format: int64 - description: The quantity of items marked as rejected + description: The quantity of items marked as rejected. pending_quantity: type: integer format: int64 - description: The quantity of items marked as pending + description: The quantity of items marked as pending. title: ReviewedItems_Base x-internal: false GetReturnableItems: @@ -1135,14 +1254,14 @@ components: $ref: '#/components/schemas/ItemReferenceId' name: type: string - description: The name of the order product + description: The name of the order product. returnable_quantity: type: integer - description: The maximum quantity of this item that can presently be requested for return + description: The maximum quantity of this item that can presently be requested for return. total: type: string format: decimal - description: The total price of this line item + description: The total price of this line item. options: type: array items: @@ -1150,24 +1269,24 @@ components: properties: display_name: type: string - description: A displayable name for the option + description: A displayable name for the option. display_value: type: string - description: A displayable value for the option - description: An item available for return - description: A collection of options configured for the order product + description: A displayable value for the option. + description: An item available for return. + description: A collection of options configured for the order product. x-internal: false ItemReferenceId: type: object properties: type: type: string - description: The reference type + description: The reference type. enum: - ORDER_PRODUCT value: type: string - description: The value identifying the returned item + description: The value identifying the returned item. required: - type - value @@ -1379,7 +1498,7 @@ components: type: string date_created: description: | - The datetime of the transaction. + The date/time of the transaction. type: string format: date-time test: @@ -1511,7 +1630,7 @@ components: type: string date_created: description: | - The datetime of the transaction. + The date/time of the transaction. type: string format: date-time test: @@ -1554,7 +1673,7 @@ components: payment_method_id: type: string description: | - The payment method ID used for this transaction + The payment method ID used for this transaction. required: - event - method @@ -1572,7 +1691,7 @@ components: Identifier for the BigCommerce Order with which this transaction is associated. date_created: description: | - The datetime of the transaction. + The date/time of the transaction. type: string format: date-time payment_instrument_token: @@ -1980,24 +2099,20 @@ components: x-internal: false x-examples: {} properties: - order_id: - type: integer - description: Order ID against which this refund will be created. This is optional for creating a single refund request. The order ID is included in the request path. - example: 1 items: type: array items: $ref: '#/components/schemas/ItemsRefund' required: - - order_id - items RefundQuote_Full: type: object title: RefundQuote_Full + x-internal: false properties: order_id: type: integer - description: ID of the order to be refunded + description: ID of the order to be refunded. total_refund_amount: $ref: '#/components/schemas/Amount' total_refund_tax_amount: @@ -2005,12 +2120,12 @@ components: example: 1.95 rounding: type: number - description: Indicates rounding value to bring refund_total to an amount refundable via payment providers (in this case to 2 decimal places) + description: Indicates rounding value to bring `refund_total` to an amount refundable with payment providers (in this case to 2 decimal places). adjustment: $ref: '#/components/schemas/AdjustmentAmount' tax_inclusive: type: boolean - description: Indicate if total_refund_amount includes tax amount + description: Indicate if `total_refund_amount` includes tax amount. refund_methods: type: array description: | @@ -2067,12 +2182,9 @@ components: In this case there are three refund methods available to the merchant: 1. Refund up to the entire order amount to store credit. 2. Mark an amount up to the full order amount as refunded externally, through a provider or means not represented directly in BC ("custom"). - 3. Refund the amount paid by store credit to store credit, and the amount paid by bank deposit via a manual refund, which will be recorded as being refunded against the bank deposit. - - + 3. Refund the amount paid by store credit to store credit, and the amount paid by bank deposit with a manual refund, which will be recorded as being refunded against the bank deposit. items: $ref: '#/components/schemas/RefundMethod' - x-internal: false RefundRequest_Post: type: object description: Request body for refund requests. @@ -2083,10 +2195,6 @@ components: type: array items: $ref: '#/components/schemas/ItemsRefund' - reason: - type: string - description: Reason for refund - example: Wrong t-shirt size payments: type: array items: @@ -2122,7 +2230,7 @@ components: item_id: 87 quantity: 1 requested_amount: null - reason: incididunt exercitation enim + reason: Wrong color meta: {} properties: data: @@ -2131,10 +2239,10 @@ components: id: type: integer description: | - Refund ID for the returned refund + Refund ID for the returned refund. order_id: type: integer - description: Order ID associated with the refund + description: Order ID associated with the refund. user_id: type: integer description: | @@ -2142,12 +2250,12 @@ components: created: type: string description: | - Timestamp of when the refund was created + Timestamp of when the refund was created. format: date-time reason: type: string description: | - Reason for refund + Reason for refund. total_amount: type: number description: | @@ -2169,29 +2277,29 @@ components: id: type: integer description: | - Reference to refund payment ID + Reference to refund payment ID. provider_id: type: string description: | - Reference to payment provider + Reference to payment provider. example: storecredit amount: type: number description: | - A non-negative two decimal place rounded value represents the amount that can be charged/refunded via payment providers. + A non-negative two decimal place rounded value represents the amount that can be charged/refunded with payment providers. example: 109.11 offline: type: boolean description: | - Indicates whether the payment was offline + Indicates whether the payment was offline. is_declined: type: boolean description: | - Indicates if this payment has been declined by the payment provider + Indicates if this payment has been declined by the payment provider. declined_message: type: string description: | - Message indicates why the payment was declined + Message indicates why the payment was declined. items: type: array items: @@ -2200,7 +2308,7 @@ components: item_type: type: string description: | - Type of item that was refunded + Type of item that was refunded. enum: - PRODUCT - GIFT_WRAPPING @@ -2214,7 +2322,7 @@ components: quantity: type: integer description: | - Quantity of item refunded. Note: this will only be populated for item_type PRODUCT + Quantity of item refunded. Note: this will only be populated for item_type PRODUCT. requested_amount: type: string description: | @@ -2224,12 +2332,12 @@ components: reason: type: string description: | - Reason for refunding an item + Reason for refunding an item. meta: $ref: '#/components/schemas/metaEmpty_Full' PostRefundsRequest: type: array - description: Request body for batch refunds + description: Request body for batch refunds. title: Refunds Request - BATCH items: $ref: '#/components/schemas/RefundRequest_Post' @@ -2243,11 +2351,11 @@ components: type: integer status: type: integer - description: HTTP status code + description: HTTP status code. example: 422 error: type: string - description: details why the request failed + description: Details why the request failed. title: FailedQuoteError x-internal: false ItemsRefund: @@ -2263,11 +2371,11 @@ components: properties: provider_id: type: string - description: Reference to payment provider + description: Reference to payment provider. example: checkout_paypalexpress amount: type: number - description: Amount refunded via this provider + description: Amount refunded with this provider. example: 9.99 offline: type: boolean @@ -2289,25 +2397,35 @@ components: Quantity Bound Item Type of refund item that capture refunding of items in the order that are of type quantity. + * `ORDER` * `PRODUCT` * `GIFT_WRAPPING` + * `SHIPPING` + * `HANDLING` + * `TAX` properties: item_type: type: string + example: PRODUCT enum: + - ORDER - PRODUCT - GIFT_WRAPPING + - SHIPPING + - HANDLING + - TAX description: Type of refund. item_id: type: integer example: 1 - description: 'Order Product ID. ' + description: Order Product ID. quantity: type: integer example: 3 reason: type: string - description: Reason for refund + example: Wrong size. + description: Reason for refund. minLength: 0 maxLength: 1000 x-internal: false @@ -2315,6 +2433,7 @@ components: type: object title: Tax Exempt (Order Level) description: 'Use this to refund a custom value at the order level. When `item_type` is set to `ORDER`, tax is not re-calculated.' + x-internal: false properties: item_type: type: string @@ -2322,6 +2441,10 @@ components: example: ORDER enum: - ORDER + item_id: + type: number + description: Numeric ID of the product in the order. + example: 1 amount: $ref: '#/components/schemas/Amount' reason: @@ -2329,22 +2452,30 @@ components: description: Reason for the refund. minLength: 0 maxLength: 1000 - x-internal: false AmountBoundItem: type: object title: Amount Bound Item - description: | + description: |- Amount Bound Item Type of refund item that capture refunding of items in the order that are of type amount. + * `PRODUCT` + * `ORDER` + * `GIFT_WRAPPING` * `SHIPPING` * `HANDLING` + * `TAX` + x-internal: false properties: item_type: type: string enum: + - PRODUCT + - ORDER + - GIFT_WRAPPING - SHIPPING - HANDLING + - TAX example: SHIPPING description: Type of refund. item_id: @@ -2353,15 +2484,20 @@ components: description: Order address ID. amount: $ref: '#/components/schemas/Amount' + quantity: + type: integer + example: 3 + description: Number of items in refund. reason: type: string + description: Explanation of refund. minLength: 0 maxLength: 1000 - x-internal: false + example: Customer requested refund MerchantOverride: type: object title: Merchant Calculated Override - description: | + description: |- Merchant explicitly provided override based on their own calculation. This override gives merchants the flexibility to @@ -2385,23 +2521,23 @@ components: properties: id: type: integer - description: Refund resource ID + description: Refund resource ID. readOnly: true order_id: type: integer - description: Reference to order id + description: Reference to order ID. user_id: type: integer - description: Reference to the user's id who create this refund. This is automatically populated by BigCommerce. + description: Reference to the user's ID who create this refund. This is automatically populated by BigCommerce. readOnly: true created: type: string format: date-time - description: Timestamp of when this refund was created + description: Timestamp of when this refund was created. readOnly: true reason: type: string - description: Reason for refund + description: Reason for refund. total_amount: $ref: '#/components/schemas/Amount' total_tax: @@ -2409,16 +2545,16 @@ components: description: 'Total tax amount refunded back to the shopper. Note: `order_level_amount` does not affect tax liability. This can be a negative amount indicating we have collected tax by refunding less to the customer.' uses_merchant_override_values: type: boolean - description: Whether refund amount and tax are provided explicitly by merchant override + description: Whether refund amount and tax are provided explicitly by merchant override. items: type: array - description: Array of items refunded + description: Array of items refunded. minItems: 1 items: $ref: '#/components/schemas/RefundItem' payments: type: array - description: An array of refund payments made to payment providers + description: An array of refund payments made to payment providers. minItems: 1 items: $ref: '#/components/schemas/RefundPayment' @@ -2428,7 +2564,7 @@ components: properties: item_type: type: string - description: Type of item that was refunded + description: Type of item that was refunded. enum: - PRODUCT - GIFT_WRAPPING @@ -2440,7 +2576,7 @@ components: description: 'order_product.id corresponding to the item_types of PRODUCT, GIFT_WRAPPING. order_address.id corresponding to the item_types of SHIPPING, HANDLING. order.id corresponding to the item_type of ORDER.' reason: type: string - description: Reason for refunding an item + description: Reason for refunding an item. quantity: type: integer description: 'Quantity of item refunded. Note: this will only be populated for item_type PRODUCT' @@ -2454,23 +2590,23 @@ components: properties: id: type: integer - description: Reference to refund payment id + description: Reference to refund payment ID. readOnly: true provider_id: type: string - description: Reference to payment provider + description: Reference to payment provider. example: storecredit amount: $ref: '#/components/schemas/Amount' offline: type: boolean - description: Indicate whether payment was offline + description: Indicate whether payment was offline. is_declined: type: boolean - description: Indicate if this payment has been declined by payment provider + description: Indicate if this payment has been declined by payment provider. declined_message: type: string - description: Message indicate why payment was declined + description: Message indicate why payment was declined. x-internal: false PaymentOption: type: object @@ -2480,20 +2616,20 @@ components: amount: 9.99 offline: true offline_provider: true - offline_reason: Multiple online refunds are not available + offline_reason: Multiple online refunds are not available. title: Payment Option properties: provider_id: type: string - description: Name of the payment method + description: Name of the payment method. example: checkout_paypalexpress provider_description: type: string - description: Description for payment provider + description: Description for payment provider. example: Paypal Express amount: type: number - description: amount to be refunded via this payment provider + description: Amount to be refunded with this payment provider. example: 9.99 offline: type: boolean @@ -2511,7 +2647,7 @@ components: Amount: type: number format: float - description: A non-negative 2 decimal place rounded value that represents the amount that can be charged/refunded via payment providers. + description: A non-negative 2 decimal place rounded value that represents the amount that can be charged/refunded with payment providers. example: 1.99 title: Amount x-internal: false @@ -2573,8 +2709,8 @@ components: description: | Determines the visibility and writeability of the field by other API consumers. - |Value|Description - |-|-| + |Value|Description | + |:-|:-| |`app_only`|Private to the app that owns the field| |`read`|Visible to other API consumers| |`write`|Open for reading and writing by other API consumers| @@ -2644,8 +2780,8 @@ components: description: | Determines the visibility and writeability of the field by other API consumers. - |Value|Description - |-|-| + |Value|Description | + |:-|:-| |`app_only`|Private to the app that owns the field| |`read`|Visible to other API consumers| |`write`|Open for reading and writing by other API consumers| @@ -2939,7 +3075,7 @@ components: title: A login URL could not be generated. Please try another request. type: /api-docs/getting-started/api-status-codes 504_GatewayTimeout: - description: 'If this occurs, you should retry the request. Typically retrying the request several times will result in a successful request; However, if you are unable to successfully make a request, please check the BigCommerce system status [here](https://status.bigcommerce.com/). A service is likely down and the request will need to be made again when it is back up (in several hours usually)' + description: 'If this occurs, you should retry the request. Typically retrying the request several times will result in a successful request; however, if you cannot successfully make a request, please check the BigCommerce system status [here](https://status.bigcommerce.com/). A service is likely down, and you will need to complete the request again when it is back up (in several hours, usually).' content: application/json: schema: @@ -2965,7 +3101,7 @@ components: type: /api-docs/getting-started/api-status-codes 400_BadRequest: description: |- - Malformed request syntax. Typically need to fix the JSON + Malformed request syntax. Typically need to fix the JSON. Body to resend successfully. content: application/json: @@ -3005,7 +3141,7 @@ components: name: error.expected.jsstring primary_contact.district: error.expected.jsstring. 503_ServiceUnavailable: - description: 'If this occurs, you should retry the request. If you are unable to successfully make a request, please check the BigCommerce system status [here](https://status.bigcommerce.com/). A service is likely down and the request will need to be made again when it is back up (in several hours usually)' + description: 'If this occurs, you should retry the request. If you cannot successfully make a request, please check the BigCommerce system status [here](https://status.bigcommerce.com/). A service is likely down, and you will need to make the request again when it is back up (in several hours, usually).' content: application/json: schema: @@ -3043,14 +3179,13 @@ components: application/json: schema: type: object - properties: {} RefundCollection_Resp: description: '' content: application/json: schema: type: object - description: Response payload for Refund resource + description: Response payload for Refund resource. properties: data: type: array @@ -3197,7 +3332,7 @@ components: item_id: 87 quantity: 1 requested_amount: null - reason: incididunt exercitation enim + reason: Wrong item sent. meta: {} parameters: OrderIdParam: @@ -3292,15 +3427,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header examples: diff --git a/reference/pages.v3.yml b/reference/pages.v3.yml index 6cc89db9f..853d3354c 100644 --- a/reference/pages.v3.yml +++ b/reference/pages.v3.yml @@ -1,4 +1,4 @@ -openapi: '3.0.3' +openapi: 3.0.3 info: title: Pages V3 version: '' @@ -11,7 +11,7 @@ info: ## Overview A **page** appears on a **site** that is associated with a **channel**. - + Some pages, such as blog pages, contact forms, and plain-text or HTML pages, are web pages in the traditional sense. They contain markup (a `body`) and load at a relative page location on the site itself (the `url`). Other pages, such as link and feed pages, make external or non-visual content available from the menu of a parent page or by direct link. ### Bulk operations @@ -215,7 +215,7 @@ paths: > #### Warning > **Pay attention to query parameters** - > If you attempt to delete multiple pages by passing more than one `pageId`` to `id:in` and one or more of them does not exist, you will receive a 404 response. However, the pages corresponding to the `pagesId`s that do exist will still be deleted. + > If you attempt to delete multiple pages by passing more than one page ID to `id:in` and one or more of them does not exist, you will receive a 404 response. However, the pages corresponding to the page IDs that do exist will still be deleted. responses: '204': $ref: '#/components/responses/HTTP204' @@ -521,14 +521,21 @@ components: required: true schema: type: string - default: 'application/json' + default: application/json ContentType: name: Content-Type in: header required: true schema: type: string - default: 'application/json' + default: application/json + storeHashPath: + schema: + type: string + name: store_hash + in: path + required: true + description: The permanent ID of the BigCommerce store. pageIdPath: schema: type: string @@ -539,11 +546,11 @@ components: includeQuery: schema: type: string - enum: + enum: - body in: query name: include - description: Include the requested property in the response. The `body` property returns the page’s markup, text, or raw content. + description: 'Include the requested property in the response. The `body` property returns the page’s markup, text, or raw content.' channelIdQuery: schema: type: integer @@ -588,66 +595,54 @@ components: name: page description: The ordered grouping of results to return. See `meta.pagination.current_page` in the response body. headers: - Content-Type: + Content-Type: description: 'The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the request body.' schema: type: string - default: 'application/json' - Accept: + default: application/json + Accept: description: 'The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body.' schema: type: string - default: 'application/json' + default: application/json X-Auth-Token: description: Your API account's access token. schema: type: string - # $ref: '' securitySchemes: X-Auth-Token: + type: apiKey + name: X-Auth-Token + in: header description: |- ## API account You can use this API with a [store API account or an app API account](https://developer.bigcommerce.com/api-docs/getting-started/rest-api-authentication). ## OAuth scopes - + | UI Name | Permission | Parameter | |:--------|:-----------|:----------| | Content | modify |`store_v2_content`| | Content | read-only |`store_v2_content_read_only`| For a [full list of OAuth scopes](https://developer.bigcommerce.com/api-docs/getting-started/rest-api-authentication#oauth-scopes), see our narrative documentation. - + ## Security header - + Include a header parameter called `X-Auth-Token` and pass it the `access_token` provided with your store API account or generated with your app's `/auth` callback. - - ```http title="Security header example" + + ```http filename="Security header example" X-Auth-Token: example_access_token ``` ## Example requests For detailed examples, consult our [X-Auth-Token example requests](https://developer.bigcommerce.com/api-docs/getting-started/authentication#x-auth-token-header-example-requests). - + ## Additional information - + [BigCommerce Terms of Service](http://www.bigcommerce.com/terms) - type: oauth2 - flows: - implicit: - authorizationUrl: 'https://store-store_hash.mybigcommerce.com/manage/settings/api-accounts/create' - scopes: - store_v2_content: Modify store content - store_v2_content_read_only: Read store content - authorizationCode: - authorizationUrl: 'https://your_app.example.com/api/auth' - tokenUrl: 'https://devtools.bigcommerce.com' - refreshUrl: 'https://your_app.example.com/api/auth' - scopes: - store_v2_content: Modify store content - store_v2_content_read_only: Read store content schemas: ResponseErrorBrief: type: object @@ -779,7 +774,7 @@ components: allOf: - properties: data: - type: array + type: object items: $ref: '#/components/schemas/Page' meta: @@ -1210,11 +1205,10 @@ components: type: boolean example: true default: true - description: |- - A boolean value that controls whether the page is available to users or visible in any navigation menus. + description: A boolean value that controls whether the page is available to users or visible in any navigation menus. parent_id: type: integer - description: ID of the parent page, if any. + description: 'ID of the parent page, if any.' example: 0 default: 0 sort_order: @@ -1241,6 +1235,11 @@ components: type: boolean description: 'When `true`, this page is not visible to merchant users who are signed in to the store control panel.' default: false + url: + type: string + description: | + Relative URL on the storefront for this page. + example: /my-store-page required: - name - type @@ -1262,7 +1261,7 @@ components: type: string description: | Relative URL on the storefront for this page. - example: '/blog/' + example: /blog/ typeContactForm: description: '' allOf: @@ -1310,13 +1309,12 @@ components: type: string description: | HTML or variable that populates the element of this page, in default/desktop view. Required in a `POST` request if the page type is `raw`. - example: '<div>Hello World!</div>' + example: <div>Hello World!</div> nullable: true content_type: type: string - description: - The MIME type of the page body. - example: 'text/html' + description: The MIME type of the page body. + example: text/html required: - body typeLink: @@ -1373,7 +1371,7 @@ components: description: Indicates whether the page is available to users and visible in any menus. parent_id: type: integer - description: ID of the parent page, if any. + description: 'ID of the parent page, if any.' example: 0 default: 0 sort_order: @@ -1420,17 +1418,17 @@ components: When you make bulk requests, an invalid input in any one entry will return 422. The entries that are valid will still be created. content: application/json: - schema: + schema: type: object properties: data: anyOf: - - $ref: '#/components/schemas/typePage' - - $ref: '#/components/schemas/typeBlog' - - $ref: '#/components/schemas/typeContactForm' - - $ref: '#/components/schemas/typeFeed' - - $ref: '#/components/schemas/typeRaw' - - $ref: '#/components/schemas/typeLink' + - $ref: '#/components/schemas/typePage' + - $ref: '#/components/schemas/typeBlog' + - $ref: '#/components/schemas/typeContactForm' + - $ref: '#/components/schemas/typeFeed' + - $ref: '#/components/schemas/typeRaw' + - $ref: '#/components/schemas/typeLink' meta: $ref: '#/components/schemas/ResponseMeta' HTTP204: @@ -1439,17 +1437,17 @@ components: description: '' content: application/problem+json: - schema: + schema: $ref: '#/components/schemas/ResponseErrorBrief' HTTP404: description: '' content: application/problem+json: - schema: + schema: $ref: '#/components/schemas/ResponseErrorDetailed' HTTP422: description: '' content: application/problem+json: - schema: + schema: $ref: '#/components/schemas/ResponseErrorDetailed' diff --git a/reference/payment_processing.yml b/reference/payment_processing.yml deleted file mode 100644 index 769e5ff0b..000000000 --- a/reference/payment_processing.yml +++ /dev/null @@ -1,1582 +0,0 @@ -openapi: '3.0.0' -info: - version: '' - title: Payment Processing - description: 'Process payments using payment instrument such as credit card. See [Payments Overview](/api-docs/store-management/payment-processing) for more information.' - termsOfService: 'https://www.bigcommerce.com/terms' - contact: - name: BigCommerce - url: 'https://www.bigcommerce.com' - email: support@bigcommerce.com -tags: - - name: Accepted Methods - - name: Access Tokens - - name: Process Payment -servers: - - url: 'https://api.bigcommerce.com/stores/{store_hash}/v3' - variables: - store_hash: - default: store_hash - description: Permanent ID of the BigCommerce store. - description: BigCommerce API Gateway - - url: 'https://payments.bigcommerce.com' - description: BigCommerce Payments Gateway -paths: - '/payments': - post: - summary: Process Payment - tags: - - Process Payment - operationId: PaymentsPost - description: 'Process payments for an order. See [Payment Processing](/api-docs/store-management/payment-processing) for more information.' - servers: - - url: 'https://payments.bigcommerce.com' - description: BigCommerce Payments Gateway - security: - - BearerPAT: [] - parameters: - - $ref: '#/components/parameters/AcceptPaymentResponse' - - $ref: '#/components/parameters/ContentType' - requestBody: - content: - application/json: - schema: - title: Payment Request - type: object - properties: - payment: - title: Payment - type: object - required: - - instrument - - payment_method_id - properties: - instrument: - anyOf: - - $ref: '#/components/schemas/Card' - - $ref: '#/components/schemas/StoredCard' - - $ref: '#/components/schemas/StoredPayPalAccount' - - $ref: '#/components/schemas/GiftCertificate' - - $ref: '#/components/schemas/StoreCredit' - payment_method_id: - description: Identifier for payment method that will be used for this payment and `id` from the Get Accepted Payment Methods API - type: string - minLength: 1 - save_instrument: - type: boolean - description: 'To use `save_instrument`, configure the payment gateway to accept stored cards.' - required: - - payment - examples: - Card: - value: - payment: - instrument: - type: card - cardholder_name: string - number: string - expiry_month: 1 - expiry_year: 0 - verification_value: stri - issue_month: 1 - issue_year: 0 - issue_number: 0 - payment_method_id: string - Stored Card: - value: - payment: - instrument: - type: stored_card - token: 8cdf7b6ea1b27119463bf9e5106639618cc77a9adc49f0069ca8b756cc15caee - verification_value: '1142' - payment_method_id: adyenv2.scheme - save_instrument: true - Stored PayPal Account: - value: - payment: - instrument: - type: stored_paypal_account - token: 2c129313bcffe4501ec5fa2764c8c16320e38c7ba9e8cdf95583b541bb05ad91 - payment_method_id: braintree.paypal - Gift Certificate: - value: - payment: - instrument: - type: gift_certificate - gift_certificate_code: ABC-DEF-GXX - payment_method_id: bigcommerce.gift_certificate - Store Credit: - value: - payment: - instrument: - type: store_credit - payment_method_id: bigcommerce.store_credit - required: true - x-examples: - application/json: - payment: - instrument: {} - payment_method_id: Lorem in - amount: 81505146 - currency_code: NYE - Payment Access Token: |- - curl -X POST \ - https://payments.bigcommerce.com/stores/{store_hash}/payments \ - -H 'Accept: application/vnd.bc.v1+json' \ - -H 'Authorization: PAT eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1NsdfasftIsIm5iZiI6MTU1MTM5MDU0MiwiaXNzIjoicGF5bWVudHMuYmlnY29tbWVyY2UuY29tIiwic3ViIjoianJhaDZnbW4iLCJqdGkiOiI3Nzg3ZmU1Zi01OWJmLTQ3ZWMtYTFmZC00ZDQ3ZTkwNjFlNWMiLCJpYXQiOjE1NTEzOTA1NDIsImRhdGEiOnsic3RvcmVfaWQiOjEwMjU2NDYsIm9yZGVyX2lkIjoyMTUsImFtb3VudCI6OTgwMCwiY3VycmVuY3kiOiJVU0QifX0.WbR90d8m4gn8wK7kPMDEoVq8B0hHC5Ul5H4Hpqq6Yvo' \ - -H 'Content-Type: application/json' \ - Vaulted Card: - payment: - instrument: - type: stored_card - token: vaulted instrument token - verification_value: '123' - payment_method_id: stripe.card - save_instrument: true - Credit Card: |- - { - "payment": { - "instrument": { - "type": "card", - "number": "4111111111111111", - "cardholder_name": "BP", - "expiry_month": 12, - "expiry_year": 2020, - "verification_value": "411" - }, - "payment_method_id": "authorizenet.card", - "save_instrument": true - } - } - description: '' - responses: - '202': - description: Payment has been successfully processed - content: - application/json: - schema: - title: Success Payment Response - type: object - properties: - id: - description: Identifier for this transaction - type: string - transaction_type: - title: Transaction Type - description: Transaction type for this payment - example: authorization - type: string - enum: - - authorization - - purchase - status: - type: string - title: Status - description: Status to indicate a success response - enum: - - success - - pending - examples: - response: - value: - id: 227d9e1e-94f8-408c-95a5-f97b30592eb7 - transaction_type: authorization - status: pending - '400': - description: Payment request has been rejected due to malformed request - content: - application/json: - schema: - title: Error Payment Response - type: object - properties: - status: - description: HTTP status code - type: integer - format: int32 - title: - description: Short summary describing the particular error - type: string - detail: - description: Detailed summary describing the particular error - type: string - type: - description: Reference that identifies the particular error - type: string - code: - description: Code representing the particular error - type: integer - format: int32 - errors: - description: '' - type: object - additionalProperties: - type: string - required: - - status - - title - - type - '401': - description: Valid authentication required - content: - application/json: - schema: - title: Error Payment Response - type: object - properties: - status: - description: HTTP status code - type: integer - format: int32 - title: - description: Short summary describing the particular error - type: string - detail: - description: Detailed summary describing the particular error - type: string - type: - description: Reference that identifies the particular error - type: string - code: - description: Code representing the particular error - type: integer - format: int32 - errors: - description: '' - type: object - additionalProperties: - type: string - required: - - status - - title - - type - '422': - description: 'Payment request has been rejected due to missing, invalid data or declined by payment provider' - content: - application/json: - schema: - title: Error Payment Response - type: object - properties: - status: - description: HTTP status code - type: integer - format: int32 - title: - description: Short summary describing the particular error - type: string - detail: - description: Detailed summary describing the particular error - type: string - type: - description: Reference that identifies the particular error - type: string - code: - description: Code representing the particular error - type: integer - format: int32 - errors: - description: '' - type: object - additionalProperties: - type: string - required: - - status - - title - - type - default: - description: Internal server error - content: - application/json: - schema: - title: Error Payment Response - type: object - properties: - status: - description: HTTP status code - type: integer - format: int32 - title: - description: Short summary describing the particular error - type: string - detail: - description: Detailed summary describing the particular error - type: string - type: - description: Reference that identifies the particular error - type: string - code: - description: Code representing the particular error - type: integer - format: int32 - errors: - description: '' - type: object - additionalProperties: - type: string - required: - - status - - title - - type - '/payments/access_tokens': - parameters: - - $ref: '#/components/parameters/Accept' - post: - description: |- - This endpoint provides the capability to create a payment access token. The payment access token is required when making request to Payment API for submitting payment for an order. - - After the token is created, use the token to [Process Payments](/docs/rest-payments/processing/process-payment#process-payment). - - **Required Fields** - * order_id - summary: Create Payment Access Token - tags: - - Access Tokens - operationId: PaymentsAccessTokensPost - servers: - - url: 'https://api.bigcommerce.com/stores/{store_hash}/v3' - variables: - store_hash: - default: store_hash - description: Permanent ID of the BigCommerce store. - description: BigCommerce API Gateway - security: - - X-Auth-Token: [] - deprecated: false - parameters: - - $ref: '#/components/parameters/ContentType' - requestBody: - content: - application/json: - schema: - title: Payment Access Token Request - type: object - properties: - order: - $ref: '#/components/schemas/Order' - required: - - order - examples: - example-1: - value: - order: - id: 1 - is_recurring: false - required: true - x-examples: - application/json: - order: - id: 44796008 - is_recurring: true - Example: - order: - id: 182 - responses: - '201': - description: Payment access token has been successfully created - headers: {} - content: - application/json: - schema: - title: Payments Access Tokens Response - type: object - properties: - data: - title: Payment Access Token - type: object - properties: - id: - description: Payment access token. This token is required in subsequent payment request to Payment API endpoint. - type: string - minLength: 1 - required: - - id - meta: - type: object - properties: {} - additionalProperties: true - description: Response metadata. - examples: - example-1: - value: - data: - id: eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE2MTUyNTA3NTksIm5iZiI6MTYxNTI0Nz E1OSwiaXNzIjoicGF5bWVudHMuYmlnY29tbWVyY2UuY29tIiwic3ViIjoieHNsM3 JoZGYzNiIsImp0aSI6IjNhOGE3NTJjLTBmNWQtNDNmNS05MzdjLTRhMTYzODBlMW YwZCIsImlhdCI6MTYxNTI0NzE1OSwiZGF0YSI6eyJzdG9yZV9pZCI6IjEwMDEzMz YzMjQiLCJvcmRlcl9pZCI6IjE2NiIsImFtb3VudCI6NDU3OTAsImN1cnJlbmN5Ij oiVVNEIn19.dpCDgOfbNrz095VARY20yYBRTOuq-W1F0ETTgf1Zhbs - meta: {} - '400': - description: Request has been rejected - content: - application/json: - schema: - title: ErrorResponse - type: object - properties: - status: - description: HTTP status code - type: integer - format: int32 - title: - description: Short summary describing the particular error - type: string - detail: - description: Detailed summary describing the particular error - type: string - type: - description: Reference that identifies the particular error - type: string - code: - description: Code representing the particular error - type: integer - format: int32 - errors: - type: object - additionalProperties: - type: string - required: - - status - - title - - type - '401': - description: Valid authentication required - content: - application/json: - schema: - title: ErrorResponse - type: object - properties: - status: - description: HTTP status code - type: integer - format: int32 - title: - description: Short summary describing the particular error - type: string - detail: - description: Detailed summary describing the particular error - type: string - type: - description: Reference that identifies the particular error - type: string - code: - description: Code representing the particular error - type: integer - format: int32 - errors: - type: object - additionalProperties: - type: string - required: - - status - - title - - type - '404': - description: Request has been rejected due to resource not being found - content: - application/json: - schema: - title: ErrorResponse - type: object - properties: - status: - description: HTTP status code - type: integer - format: int32 - title: - description: Short summary describing the particular error - type: string - detail: - description: Detailed summary describing the particular error - type: string - type: - description: Reference that identifies the particular error - type: string - code: - description: Code representing the particular error - type: integer - format: int32 - errors: - type: object - additionalProperties: - type: string - required: - - status - - title - - type - '409': - description: Request has been rejected due to conflict with the current state of the target resource - content: - application/json: - schema: - title: ErrorResponse - type: object - properties: - status: - description: HTTP status code - type: integer - format: int32 - title: - description: Short summary describing the particular error - type: string - detail: - description: Detailed summary describing the particular error - type: string - type: - description: Reference that identifies the particular error - type: string - code: - description: Code representing the particular error - type: integer - format: int32 - errors: - type: object - additionalProperties: - type: string - required: - - status - - title - - type - '422': - description: Request has been rejected due to missing or invalid data - content: - application/json: - schema: - title: ErrorResponse - type: object - properties: - status: - description: HTTP status code - type: integer - format: int32 - title: - description: Short summary describing the particular error - type: string - detail: - description: Detailed summary describing the particular error - type: string - type: - description: Reference that identifies the particular error - type: string - code: - description: Code representing the particular error - type: integer - format: int32 - errors: - type: object - additionalProperties: - type: string - required: - - status - - title - - type - default: - description: Internal server error - content: - application/json: - schema: - title: ErrorResponse - type: object - properties: - status: - description: HTTP status code - type: integer - format: int32 - title: - description: Short summary describing the particular error - type: string - detail: - description: Detailed summary describing the particular error - type: string - type: - description: Reference that identifies the particular error - type: string - code: - description: Code representing the particular error - type: integer - format: int32 - errors: - type: object - additionalProperties: - type: string - required: - - status - - title - - type - '/payments/methods': - parameters: - - $ref: '#/components/parameters/Accept' - get: - description: |- - Returns a list of accepted payment methods based on the `order_id` or `checkout_id`. - - **Notes** - * Use the [Create an Order](/docs/rest-management/orders#create-an-order) endpoint to generate the `order_id`. - * Orders created will be set to incomplete order status. - * The cart ID and checkout ID are the same. - - **Required Fields** - * `order_id` or `checkout_id` - summary: Get Accepted Payment Methods - tags: - - Accepted Methods - operationId: PaymentsMethodsGet - servers: - - url: 'https://api.bigcommerce.com/stores/{store_hash}/v3' - variables: - store_hash: - default: store_hash - description: Permanent ID of the BigCommerce store. - description: BigCommerce API Gateway - security: - - X-Auth-Token: [] - deprecated: false - parameters: - - name: order_id - in: query - description: Identifier for the order - schema: - type: integer - format: int32 - exclusiveMinimum: false - exclusiveMaximum: false - - name: checkout_id - in: query - description: Identifier for the checkout (same as the cart ID) - schema: - type: string - exclusiveMinimum: false - exclusiveMaximum: false - responses: - '200': - $ref: '#/components/responses/paymentsMethods_Resp' - '400': - description: Request has been rejected - content: - application/json: - schema: - title: ErrorResponse - type: object - properties: - status: - description: HTTP status code - type: integer - format: int32 - title: - description: Short summary describing the particular error - type: string - detail: - description: Detailed summary describing the particular error - type: string - type: - description: Reference that identifies the particular error - type: string - code: - description: Code representing the particular error - type: integer - format: int32 - errors: - type: object - additionalProperties: - type: string - required: - - status - - title - - type - '401': - description: Valid authentication required - content: - application/json: - schema: - title: ErrorResponse - type: object - properties: - status: - description: HTTP status code - type: integer - format: int32 - title: - description: Short summary describing the particular error - type: string - detail: - description: Detailed summary describing the particular error - type: string - type: - description: Reference that identifies the particular error - type: string - code: - description: Code representing the particular error - type: integer - format: int32 - errors: - type: object - additionalProperties: - type: string - required: - - status - - title - - type - '404': - description: Request has been rejected due to resource not being found - content: - application/json: - schema: - title: ErrorResponse - type: object - properties: - status: - description: HTTP status code - type: integer - format: int32 - title: - description: Short summary describing the particular error - type: string - detail: - description: Detailed summary describing the particular error - type: string - type: - description: Reference that identifies the particular error - type: string - code: - description: Code representing the particular error - type: integer - format: int32 - errors: - type: object - additionalProperties: - type: string - required: - - status - - title - - type - '422': - description: Request has been rejected due to missing or invalid data - content: - application/json: - schema: - title: ErrorResponse - type: object - properties: - status: - description: HTTP status code - type: integer - format: int32 - title: - description: Short summary describing the particular error - type: string - detail: - description: Detailed summary describing the particular error - type: string - type: - description: Reference that identifies the particular error - type: string - code: - description: Code representing the particular error - type: integer - format: int32 - errors: - type: object - additionalProperties: - type: string - required: - - status - - title - - type - default: - description: Internal server error - content: - application/json: - schema: - title: ErrorResponse - type: object - properties: - status: - description: HTTP status code - type: integer - format: int32 - title: - description: Short summary describing the particular error - type: string - detail: - description: Detailed summary describing the particular error - type: string - type: - description: Reference that identifies the particular error - type: string - code: - description: Code representing the particular error - type: integer - format: int32 - errors: - type: object - additionalProperties: - type: string - required: - - status - - title - - type -components: - parameters: - AcceptPaymentResponse: - name: Accept - in: header - schema: - type: string - enum: - - 'application/vnd.bc.v1+json' - default: 'application/vnd.bc.v1+json' - required: true - description: This required value must be `application/vnd.bc.v1+json`. - Accept: - name: Accept - in: header - required: true - description: 'The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body.' - schema: - type: string - default: 'application/json' - ContentType: - name: Content-Type - in: header - required: true - description: 'The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the request body.' - schema: - type: string - default: 'application/json' - responses: - paymentsMethods_Resp: - description: '' - content: - application/json: - schema: - title: Payments Methods Response - type: object - properties: - data: - type: array - items: - $ref: '#/components/schemas/paymentMethod_Full' - meta: - type: object - properties: {} - additionalProperties: true - description: Response metadata. - examples: - response: - value: - data: - - id: bigcommerce.gift_certificate - name: Gift Certificate - test_mode: false - type: gift_certificate - supported_instruments: [] - stored_instruments: [] - - id: bigcommerce.store_credit - name: Store Credit - test_mode: false - type: store_credit - supported_instruments: [] - stored_instruments: [] - - id: stripe.card - name: Stripe - test_mode: true - type: card - supported_instruments: - - instrument_type: VISA - verification_value_required: true - - instrument_type: MASTERCARD - verification_value_required: true - - instrument_type: AMEX - verification_value_required: true - - instrument_type: DISCOVER - verification_value_required: true - - instrument_type: JCB - verification_value_required: true - - instrument_type: DINERS_CLUB - verification_value_required: true - - instrument_type: STORED_CARD - verification_value_required: true - stored_instruments: - - type: stored_card - brand: VISA - expiry_month: 9 - expiry_year: 2020 - issuer_identification_number: '424242' - last_4: '4242' - token: 050a1e5c982e5905288ec5ec33f292772762033a0704f46fccb16bf1940b51ef - is_default: true - meta: {} - paymentAccessToken_Resp: - description: '' - content: - application/json: - schema: - title: Payments Access Tokens Response - type: object - properties: - data: - $ref: '#/components/schemas/PaymentAccessToken' - securitySchemes: - X-Auth-Token: - name: X-Auth-Token - description: |- - ### OAuth scopes - - | UI Name | Permission | Parameter | - |:--------|:-----------|:----------| - | Create Payments | create | `store_payments_access_token_create` | - | Get Payment Methods | read-only | `store_payments_methods_read` | - - ### Authentication header - - | Header | Argument | Description | - |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | - - ### Further reading - - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). - - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). - - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). - type: apiKey - in: header - BearerPAT: - description: |- - ### OAuth scopes - - The required scopes are granted to the `payment_access_token` upon generation. - - ### Authentication header - - | Header | Argument | Description | - |:-------|:---------|:------------| - |`Authorization`|`PAT {{PAYMENT_ACCESS_TOKEN}}`| Obtained using the Create Access Token endpoint.| - - ### Further reading - - For an outline of the Process Payment API call flow and more information about authenticating, see [Authentication and Example Requests](/api-docs/getting-started/authentication#bigcommerce-generated-jwts). - - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). - type: http - scheme: bearer - bearerFormat: 'PAT {{PAYMENT_ACCESS_TOKEN}}' - schemas: - PaymentRequest: - title: Payment Request - type: object - properties: - payment: - title: Payment - type: object - required: - - instrument - - payment_method_id - properties: - amount: - description: Amount in smallest currency unit - type: integer - format: int32 - currency_code: - description: Currency code - type: string - pattern: '^[A-Z]{3}$' - instrument: - description: '' - type: object - payment_method_id: - description: Identifier for payment method that will be used for this payment - type: string - minLength: 1 - required: - - payment - x-internal: false - Payment: - title: Payment - type: object - properties: - amount: - description: Amount in smallest currency unit - type: integer - format: int32 - currency_code: - description: Currency code - type: string - pattern: '^[A-Z]{3}$' - instrument: - description: '' - type: object - payment_method_id: - description: Identifier for payment method that will be used for this payment - type: string - minLength: 1 - required: - - instrument - - payment_method_id - x-internal: false - SuccessPaymentResponse: - title: Success Payment Response - type: object - properties: - id: - description: Identifier for this transaction - type: string - transaction_type: - title: Transaction Type - description: Transaction type for this payment - example: authorization - type: string - enum: - - authorization - - purchase - status: - type: string - title: Status - description: Status to indicate a success response - enum: - - success - - pending - x-internal: false - TransactionType: - title: Transaction Type - description: Transaction type for this payment - example: authorization - type: string - enum: - - authorization - - purchase - x-internal: false - Status: - type: string - title: Status - description: Status to indicate a success response - enum: - - success - - pending - x-internal: false - ErrorPaymentResponse: - title: Error Payment Response - type: object - properties: - status: - description: HTTP status code - type: integer - format: int32 - title: - description: Short summary describing the particular error - type: string - detail: - description: Detailed summary describing the particular error - type: string - type: - description: Reference that identifies the particular error - type: string - code: - description: Code representing the particular error - type: integer - format: int32 - errors: - description: '' - type: object - additionalProperties: - type: string - required: - - status - - title - - type - x-internal: false - Card: - title: Card - type: object - x-examples: - example-1: - type: card - cardholder_name: string - number: string - expiry_month: 1 - expiry_year: 0 - verification_value: stri - issue_month: 1 - issue_year: 0 - issue_number: 0 - x-internal: false - properties: - type: - type: string - default: card - example: card - description: Type to classify this payment instrument (required) - cardholder_name: - type: string - minLength: 1 - description: Cardholderʼs full name (required) - number: - type: string - minLength: 1 - description: Credit card number (required) - expiry_month: - type: integer - format: int32 - minimum: 1 - maximum: 12 - description: Expiry month of this card (required) - expiry_year: - type: integer - format: int32 - description: Expiry year of this card (required) - verification_value: - type: string - minLength: 3 - maxLength: 4 - description: Verification value of this card (CVV) - issue_month: - type: integer - description: Issue month of this card - format: int32 - minimum: 1 - maximum: 12 - issue_year: - type: integer - format: int32 - description: Issue year of this card - issue_number: - type: integer - format: int32 - description: Issue number of this card - StoredCard: - title: Stored Card - type: object - x-internal: false - x-examples: - example-1: - type: stored_card - token: stringstringstringstringstringstringstringstringstringstringstri - verification_value: 1142 - properties: - type: - description: Type to classify this payment instrument (required) - example: stored_card - type: string - default: stored_card - token: - description: Identifier representing this stored card (required) - type: string - minLength: 64 - maxLength: 64 - verification_value: - type: string - description: Verification value of this card (CVV) - minLength: 3 - maxLength: 4 - BasePaymentResponse: - title: Base Payment Response - type: object - properties: - id: - description: Identifier for this transaction - type: string - transaction_type: - title: Transaction Type - description: Transaction type for this payment - example: authorization - type: string - enum: - - authorization - - purchase - x-internal: false - PendingPaymentResponse: - title: Pending Payment Response - type: object - properties: - id: - description: Identifier for this transaction - type: string - transaction_type: - title: Transaction Type - description: Transaction type for this payment - example: authorization - type: string - enum: - - authorization - - purchase - status: - type: string - title: Status - description: Status to indicate a success response - enum: - - success - - pending - x-internal: false - StoredPayPalAccount: - title: StoredPayPalAccount - type: object - x-internal: false - properties: - type: - type: string - description: Type to classify this payment instrument (required) - enum: - - stored_paypal_account - token: - description: Identifier representing this stored PayPal account (required) - type: string - minLength: 64 - maxLength: 64 - x-examples: - example-1: - type: stored_paypal_account - token: stringstringstringstringstringstringstringstringstringstringstri - Order: - title: Order - type: object - properties: - id: - description: Identifier for the order - type: integer - minimum: 1 - format: int32 - is_recurring: - description: Whether this is a recurring order. If the order is recurring this field should be set to true in order to let the payment gateway know. - example: false - type: boolean - default: false - required: - - id - x-examples: - example-1: - id: 1 - is_recurring: false - x-internal: false - PaymentAccessTokenRequest: - title: Payment Access Token Request - type: object - properties: - order: - title: Order - type: object - required: - - id - properties: - id: - description: Identifier for the order - type: integer - minimum: 1 - format: int32 - is_recurring: - description: Whether this is a recurring order. If the order is recurring this field should be set to true in order to let the payment gateway know. - example: false - type: boolean - default: false - required: - - order - x-internal: false - PaymentAccessToken: - title: Payment Access Token - type: object - properties: - id: - description: Payment access token. This token is required in subsequent payment request to Payment API endpoint. - type: string - minLength: 1 - required: - - id - x-internal: false - paymentMethodStoredInstrument: - title: paymentMethodStoredInstrument - type: object - properties: - brand: - description: Brand of this card such as VISA or Mastercard - type: string - minLength: 1 - expiry_month: - description: Expiry month of this card - type: integer - minimum: 1 - maximum: 12 - format: int32 - expiry_year: - description: Expiry year of this card - type: integer - format: int32 - issuer_identification_number: - description: Issuer identification number of this card. This is extracted from the card when the order is payed for. - type: string - minLength: 6 - maxLength: 6 - last_4: - description: Last four numbers of this card - type: string - minLength: 4 - maxLength: 4 - token: - description: A BigCommerce-generated identifier that represents the stored card. - type: string - minLength: 64 - maxLength: 64 - is_default: - description: Whether this instrument is a default instrument - example: false - type: boolean - default: false - type: - description: Type to classify this stored card - example: stored_card - type: string - default: stored_card - required: - - brand - - expiry_month - - expiry_year - - issuer_identification_number - - last_4 - - token - - is_default - - type - x-examples: - example-1: - brand: string - expiry_month: 1 - expiry_year: 0 - issuer_identification_number: string - last_4: stri - token: stringstringstringstringstringstringstringstringstringstringstri - is_default: false - type: stored_card - x-internal: false - paymentMethod_Full: - title: paymentMethod_Full - type: object - properties: - id: - description: Identifier for this payment method - type: string - minLength: 1 - name: - description: Name of this payment method - type: string - minLength: 1 - stored_instruments: - type: array - items: - $ref: '#/components/schemas/paymentMethodStoredInstrument' - supported_instruments: - type: array - items: - title: Supported Card Instrument - type: object - properties: - instrument_type: - title: InstrumentType - description: Type of this instrument - example: VISA - type: string - enum: - - VISA - - MASTERCARD - - DISCOVER - - AMEX - - DINERS_CLUB - - JCB - - DANKORT - - MAESTRO - - STORED_CARD - verification_value_required: - description: Whether verification value is required for payment - type: boolean - required: - - instrument_type - test_mode: - description: Whether this payment method is on test mode - example: false - type: boolean - default: false - type: - description: Type to classify this payment method - example: card - type: string - default: card - required: - - id - - name - - supported_instruments - - test_mode - - type - x-examples: - example-1: - id: string - name: string - stored_instruments: - - brand: string - expiry_month: 1 - expiry_year: 0 - issuer_identification_number: string - last_4: stri - token: stringstringstringstringstringstringstringstringstringstringstri - is_default: false - type: stored_card - supported_instruments: - - instrument_type: VISA - verification_value_required: true - test_mode: false - type: card - x-internal: false - SupportedCardInstrument: - title: Supported Card Instrument - type: object - properties: - instrument_type: - title: InstrumentType - description: Type of this instrument - example: VISA - type: string - enum: - - VISA - - MASTERCARD - - DISCOVER - - AMEX - - DINERS_CLUB - - JCB - - DANKORT - - MAESTRO - - STORED_CARD - verification_value_required: - description: Whether verification value is required for payment - type: boolean - required: - - instrument_type - x-internal: false - Error: - title: Error - type: object - properties: - status: - description: HTTP status code - type: integer - format: int32 - title: - description: Short summary describing the particular error - type: string - detail: - description: Detailed summary describing the particular error - type: string - type: - description: Reference that identifies the particular error - type: string - code: - description: Code representing the particular error - type: integer - format: int32 - required: - - status - - title - - type - x-internal: false - ErrorResponse: - title: ErrorResponse - type: object - properties: - status: - description: HTTP status code - type: integer - format: int32 - title: - description: Short summary describing the particular error - type: string - detail: - description: Detailed summary describing the particular error - type: string - type: - description: Reference that identifies the particular error - type: string - code: - description: Code representing the particular error - type: integer - format: int32 - errors: - type: object - additionalProperties: - type: string - required: - - status - - title - - type - x-internal: false - InstrumentType: - title: InstrumentType - description: Type of this instrument - example: VISA - type: string - enum: - - VISA - - MASTERCARD - - DISCOVER - - AMEX - - DINERS_CLUB - - JCB - - DANKORT - - MAESTRO - - STORED_CARD - x-internal: false - StoredPayPalAccountInstrument: - title: StoredPayPalAccountInstrument - type: object - properties: - email: - type: string - format: email - description: Email address of this stored account - token: - type: string - description: Identifier representing this stored account - minLength: 64 - maxLength: 64 - is_default: - type: boolean - description: Whether this instrument is a default instrument - default: false - type: - type: string - description: Type to classify this stored account - enum: - - stored_paypal_account - required: - - email - - token - - is_default - - type - x-internal: false - SupportedPayPalAccountInstrument: - title: SupportedPayPalAccountInstrument - type: object - properties: - instrument_type: - type: string - description: Type of this instrument - enum: - - STORED_PAYPAL_ACCOUNT - required: - - instrument_type - x-internal: false - GiftCertificate: - title: GiftCertificate - type: object - properties: - type: - type: string - example: gift_certificate - gift_certificate_code: - type: string - example: ABC-DEF-GXX - x-examples: - example-1: - type: gift_certificate - gift_certificate_code: ABC-DEF-GXX - StoreCredit: - title: StoreCredit - type: object - properties: - type: - type: string - example: store_credit - x-examples: - example-1: - type: store_credit diff --git a/reference/payments/accepted-methods_payments.v3.yml b/reference/payments/accepted-methods_payments.v3.yml new file mode 100644 index 000000000..3cb37ccca --- /dev/null +++ b/reference/payments/accepted-methods_payments.v3.yml @@ -0,0 +1,496 @@ +openapi: '3.0.0' +info: + version: '' + title: Accepted Payment Methods + description: | + > The Payments API processes payments using payment instruments such as credit cards or PayPal accounts. To learn more about Payments, see the [Payments Overview](/docs/store-operations/payments). + + The [Get accepted payment methods](/docs/rest-payments/methods#get-accepted-payment-methods) endpoint returns information about the payment methods each configured payment gateway accepts. This information optimizes your implementation's likelihood of making successful payments requests + that return errors solely when payment methods fail, without making API calls to the gateway prior to running the payment. + + For a list of compatible payment gateways, as well as a guide through the API call sequence needed to make charges, see the [Payments Overview](/docs/store-operations/payments#compatible-payment-gateways). + + This endpoint uses the X-Auth-Token header to authenticate. For an X-Auth-Token example request, see the related section in our [Authentication article](/docs/start/authentication#x-auth-token-header-example-requests). + + > To learn more about authenticating Payments endpoints, locate the **Authentication** section at the top of each endpoint, then click **Show Details**. + + ## Resources + + * [Payments Overview](/docs/store-operations/payments) + * [Process payments authentication example request](/docs/start/authentication#bigcommerce-generated-jwts) + * [Orders Overview](/docs/store-operations/orders) + + ### Webhooks + + * [Carts](https://developer.bigcommerce.com/api-docs/channels/guide/webhooks#carts) + * [Orders](https://developer.bigcommerce.com/api-docs/store-management/webhooks/webhook-events#orders) + * [Price list assignment](https://developer.bigcommerce.com/api-docs/channels/guide/webhooks#price-list-assignments) + + ### Additional Payments endpoints + + * [Create a Payment Access Token](/docs/rest-payments/tokens#create-payment-access-token) + * [Process payments](/docs/rest-payments/processing#process-payment) + * [Get a customer's stored instruments](/docs/rest-management/customers/customer-stored-instruments#get-stored-instruments) + + + termsOfService: 'https://www.bigcommerce.com/terms' + contact: + name: BigCommerce + url: 'https://www.bigcommerce.com' + email: support@bigcommerce.com +tags: + - name: Methods +servers: + - url: 'https://api.bigcommerce.com/stores/{store_hash}/v3' + variables: + store_hash: + default: store_hash + description: Permanent ID of the BigCommerce store. + description: BigCommerce API Gateway +security: + - X-Auth-Token: [] +paths: + '/payments/methods': + parameters: + - $ref: '#/components/parameters/Accept' + get: + description: |- + Returns a list of accepted payment methods based on the `order_id` or `checkout_id`. + + **Notes** + * Use the [Create an Order](/docs/rest-management/orders#create-an-order) endpoint to generate the `order_id`. + * Orders created will be set to incomplete order status. + * The cart ID and checkout ID are the same. + + **Required Fields** + * `order_id` or `checkout_id` + summary: Get Accepted Payment Methods + tags: + - Methods + operationId: PaymentsMethodsGet + deprecated: false + parameters: + - name: order_id + in: query + description: Identifier for the order + schema: + type: integer + format: int32 + exclusiveMinimum: false + exclusiveMaximum: false + - name: checkout_id + in: query + description: Identifier for the checkout (same as the cart ID) + schema: + type: string + exclusiveMinimum: false + exclusiveMaximum: false + responses: + '200': + $ref: '#/components/responses/paymentsMethods_Resp' + '400': + description: Request has been rejected + content: + application/json: + schema: + title: ErrorResponse + type: object + properties: + status: + description: HTTP status code + type: integer + format: int32 + title: + description: Short summary describing the particular error + type: string + detail: + description: Detailed summary describing the particular error + type: string + type: + description: Reference that identifies the particular error + type: string + code: + description: Code representing the particular error + type: integer + format: int32 + errors: + type: object + additionalProperties: + type: string + required: + - status + - title + - type + '401': + description: Valid authentication required + content: + application/json: + schema: + title: ErrorResponse + type: object + properties: + status: + description: HTTP status code + type: integer + format: int32 + title: + description: Short summary describing the particular error + type: string + detail: + description: Detailed summary describing the particular error + type: string + type: + description: Reference that identifies the particular error + type: string + code: + description: Code representing the particular error + type: integer + format: int32 + errors: + type: object + additionalProperties: + type: string + required: + - status + - title + - type + '404': + description: Request has been rejected due to resource not being found + content: + application/json: + schema: + title: ErrorResponse + type: object + properties: + status: + description: HTTP status code + type: integer + format: int32 + title: + description: Short summary describing the particular error + type: string + detail: + description: Detailed summary describing the particular error + type: string + type: + description: Reference that identifies the particular error + type: string + code: + description: Code representing the particular error + type: integer + format: int32 + errors: + type: object + additionalProperties: + type: string + required: + - status + - title + - type + '422': + description: Request has been rejected due to missing or invalid data + content: + application/json: + schema: + title: ErrorResponse + type: object + properties: + status: + description: HTTP status code + type: integer + format: int32 + title: + description: Short summary describing the particular error + type: string + detail: + description: Detailed summary describing the particular error + type: string + type: + description: Reference that identifies the particular error + type: string + code: + description: Code representing the particular error + type: integer + format: int32 + errors: + type: object + additionalProperties: + type: string + required: + - status + - title + - type + default: + description: Internal server error + content: + application/json: + schema: + title: ErrorResponse + type: object + properties: + status: + description: HTTP status code + type: integer + format: int32 + title: + description: Short summary describing the particular error + type: string + detail: + description: Detailed summary describing the particular error + type: string + type: + description: Reference that identifies the particular error + type: string + code: + description: Code representing the particular error + type: integer + format: int32 + errors: + type: object + additionalProperties: + type: string + required: + - status + - title + - type +components: + parameters: + Accept: + name: Accept + in: header + required: true + description: 'The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body.' + schema: + type: string + default: 'application/json' + schemas: + paymentMethodStoredInstrument: + title: paymentMethodStoredInstrument + type: object + properties: + brand: + description: Brand of this card such as VISA or Mastercard + type: string + minLength: 1 + expiry_month: + description: Expiry month of this card + type: integer + minimum: 1 + maximum: 12 + format: int32 + expiry_year: + description: Expiry year of this card + type: integer + format: int32 + issuer_identification_number: + description: Issuer identification number of this card. This is extracted from the card when the order is paid for. + type: string + minLength: 6 + maxLength: 6 + last_4: + description: Last four numbers of this card + type: string + minLength: 4 + maxLength: 4 + token: + description: A BigCommerce-generated identifier that represents the stored card. + type: string + minLength: 64 + maxLength: 64 + is_default: + description: Whether this instrument is a default instrument + example: false + type: boolean + default: false + type: + description: Type to classify this stored card + example: stored_card + type: string + default: stored_card + required: + - brand + - expiry_month + - expiry_year + - issuer_identification_number + - last_4 + - token + - is_default + - type + x-examples: + example-1: + brand: string + expiry_month: 1 + expiry_year: 0 + issuer_identification_number: string + last_4: stri + token: stringstringstringstringstringstringstringstringstringstringstri + is_default: false + type: stored_card + x-internal: false + paymentMethod_Full: + title: paymentMethod_Full + type: object + properties: + id: + description: Identifier for this payment method + type: string + minLength: 1 + name: + description: Name of this payment method + type: string + minLength: 1 + stored_instruments: + type: array + items: + $ref: '#/components/schemas/paymentMethodStoredInstrument' + supported_instruments: + type: array + items: + title: Supported Card Instrument + type: object + properties: + instrument_type: + title: InstrumentType + description: Type of this instrument + example: VISA + type: string + enum: + - VISA + - MASTERCARD + - DISCOVER + - AMEX + - DINERS_CLUB + - JCB + - DANKORT + - MAESTRO + - STORED_CARD + verification_value_required: + description: Whether verification value is required for payment + type: boolean + required: + - instrument_type + test_mode: + description: Whether this payment method is on test mode + example: false + type: boolean + default: false + type: + description: Type to classify this payment method + example: card + type: string + default: card + required: + - id + - name + - supported_instruments + - test_mode + - type + x-examples: + example-1: + id: string + name: string + stored_instruments: + - brand: string + expiry_month: 1 + expiry_year: 0 + issuer_identification_number: string + last_4: stri + token: stringstringstringstringstringstringstringstringstringstringstri + is_default: false + type: stored_card + supported_instruments: + - instrument_type: VISA + verification_value_required: true + test_mode: false + type: card + x-internal: false + responses: + paymentsMethods_Resp: + description: '' + content: + application/json: + schema: + title: Payments Methods Response + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/paymentMethod_Full' + meta: + type: object + properties: {} + additionalProperties: true + description: Response metadata. + examples: + response: + value: + data: + - id: bigcommerce.gift_certificate + name: Gift Certificate + test_mode: false + type: gift_certificate + supported_instruments: [] + stored_instruments: [] + - id: bigcommerce.store_credit + name: Store Credit + test_mode: false + type: store_credit + supported_instruments: [] + stored_instruments: [] + - id: stripe.card + name: Stripe + test_mode: true + type: card + supported_instruments: + - instrument_type: VISA + verification_value_required: true + - instrument_type: MASTERCARD + verification_value_required: true + - instrument_type: AMEX + verification_value_required: true + - instrument_type: DISCOVER + verification_value_required: true + - instrument_type: JCB + verification_value_required: true + - instrument_type: DINERS_CLUB + verification_value_required: true + - instrument_type: STORED_CARD + verification_value_required: true + stored_instruments: + - type: stored_card + brand: VISA + expiry_month: 9 + expiry_year: 2020 + issuer_identification_number: '424242' + last_4: '4242' + token: 050a1e5c982e5905288ec5ec33f292772762033a0704f46fccb16bf1940b51ef + is_default: true + meta: {} + securitySchemes: + X-Auth-Token: + name: X-Auth-Token + description: |- + ### OAuth scopes + + | UI Name | Permission | Parameter | + |:--------|:-----------|:----------| + | Create Payments | create | `store_payments_access_token_create` | + | Get Payment Methods | read-only | `store_payments_methods_read` | + + ### Authentication header + + | Header | Argument | Description | + |:-------|:---------|:------------| + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | + + ### Further reading + + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). + + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). + + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). + type: apiKey + in: header + diff --git a/reference/payments/access-tokens_payments.v3.yml b/reference/payments/access-tokens_payments.v3.yml new file mode 100644 index 000000000..25211c673 --- /dev/null +++ b/reference/payments/access-tokens_payments.v3.yml @@ -0,0 +1,394 @@ +openapi: '3.0.0' +info: + version: '' + title: Payment Access Token + description: | + > The Payments API processes payments using payment instruments such as credit cards or PayPal accounts. To learn more about Payments, see the [Payments Overview](/docs/store-operations/payments). + + BigCommerce payments requests require a Payment Access Token, or _PAT_, which is a single use BigCommerce-generated JWT that's tied to the particular **order** for which the shopper authorizes BigCommerce to submit a payment. + + To get a valid PAT, submit the order number to the [Create a Payment Access Token](/docs/rest-payments/tokens#create-payment-access-token) endpoint. Authenticate using an [API account access token](/docs/start/authentication/api-accounts#api-accounts) with the [Create payments](/docs/start/authentication/api-accounts#token-creation-scopes) scope as the value of the X-Auth-Token header. + + You can also generate a PAT during checkout by using the `completeCheckout` mutation in the [GraphQL Storefront API](/docs/storefront/cart-checkout/guide/graphql-storefront#handling-payments). + + For a guide through the API call sequence needed to create a PAT and make charges, see the [Payments Overview](/docs/store-operations/payments#compatible-payment-gateways). + + > To learn more about authenticating Payments endpoints, locate the **Authentication** section at the top of each endpoint, then click **Show Details**. + + ## Resources + + * [Payments Overview](/docs/store-operations/payments) + * [Process payments authentication example request](/docs/start/authentication#bigcommerce-generated-jwts) + * [Orders Overview](/docs/store-operations/orders) + + ### Webhooks + + * [Carts](https://developer.bigcommerce.com/api-docs/channels/guide/webhooks#carts) + * [Orders](https://developer.bigcommerce.com/api-docs/store-management/webhooks/webhook-events#orders) + * [Price list assignment](https://developer.bigcommerce.com/api-docs/channels/guide/webhooks#price-list-assignments) + + + ### Additional Payments endpoints + + * [Get accepted payment methods](/docs/rest-payments/methods#get-accepted-payment-methods) + * [Process payments](/docs/rest-payments/processing#process-payment) + * [Get a customer's stored instruments](/docs/rest-management/customers/customer-stored-instruments#get-stored-instruments) + termsOfService: 'https://www.bigcommerce.com/terms' + contact: + name: BigCommerce + url: 'https://www.bigcommerce.com' + email: support@bigcommerce.com +tags: + - name: Tokens +servers: + - url: 'https://api.bigcommerce.com/stores/{store_hash}/v3' + variables: + store_hash: + default: store_hash + description: Permanent ID of the BigCommerce store. + description: BigCommerce API Gateway +security: + - X-Auth-Token: [] +paths: + '/payments/access_tokens': + parameters: + - $ref: '#/components/parameters/Accept' + post: + description: |- + Use this endpoint to create a payment access token. A payment access token is required to process payments with the BigCommerce API. + + You can also generate a payment access token during checkout by using the `completeCheckout` mutation in the [GraphQL Storefront API](/docs/storefront/cart-checkout/guide/graphql-storefront#handling-payments). + + After the token is created, use the token to [Process a payment](/docs/rest-payments/processing#process-payment). + + **Required Fields** + * order_id + summary: Create Payment Access Token + tags: + - Tokens + operationId: PaymentsAccessTokensPost + deprecated: false + parameters: + - $ref: '#/components/parameters/ContentType' + requestBody: + content: + application/json: + schema: + title: Payment Access Token Request + type: object + properties: + order: + $ref: '#/components/schemas/Order' + required: + - order + examples: + example-1: + value: + order: + id: 1 + is_recurring: false + required: true + x-examples: + application/json: + order: + id: 44796008 + is_recurring: true + Example: + order: + id: 182 + responses: + '201': + description: Payment access token has been successfully created. + headers: {} + content: + application/json: + schema: + title: Payments Access Tokens Response + type: object + properties: + data: + title: Payment Access Token + type: object + properties: + id: + description: Payment access token. This token is required in the subsequent request to the [Process a payment](/docs/rest-payments/processing#process-payment) endpoint. + type: string + minLength: 1 + required: + - id + meta: + type: object + properties: {} + additionalProperties: true + description: Response metadata. + examples: + example-1: + value: + data: + id: eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE2MTUyNTA3NTksIm5iZiI6MTYxNTI0Nz E1OSwiaXNzIjoicGF5bWVudHMuYmlnY29tbWVyY2UuY29tIiwic3ViIjoieHNsM3 JoZGYzNiIsImp0aSI6IjNhOGE3NTJjLTBmNWQtNDNmNS05MzdjLTRhMTYzODBlMW YwZCIsImlhdCI6MTYxNTI0NzE1OSwiZGF0YSI6eyJzdG9yZV9pZCI6IjEwMDEzMz YzMjQiLCJvcmRlcl9pZCI6IjE2NiIsImFtb3VudCI6NDU3OTAsImN1cnJlbmN5Ij oiVVNEIn19.dpCDgOfbNrz095VARY20yYBRTOuq-W1F0ETTgf1Zhbs + meta: {} + '400': + description: Request has been rejected + content: + application/json: + schema: + title: ErrorResponse + type: object + properties: + status: + description: HTTP status code + type: integer + format: int32 + title: + description: Short summary describing the particular error + type: string + detail: + description: Detailed summary describing the particular error + type: string + type: + description: Reference that identifies the particular error + type: string + code: + description: Code representing the particular error + type: integer + format: int32 + errors: + type: object + additionalProperties: + type: string + required: + - status + - title + - type + '401': + description: Valid authentication required + content: + application/json: + schema: + title: ErrorResponse + type: object + properties: + status: + description: HTTP status code + type: integer + format: int32 + title: + description: Short summary describing the particular error + type: string + detail: + description: Detailed summary describing the particular error + type: string + type: + description: Reference that identifies the particular error + type: string + code: + description: Code representing the particular error + type: integer + format: int32 + errors: + type: object + additionalProperties: + type: string + required: + - status + - title + - type + '404': + description: Request has been rejected due to resource not being found + content: + application/json: + schema: + title: ErrorResponse + type: object + properties: + status: + description: HTTP status code + type: integer + format: int32 + title: + description: Short summary describing the particular error + type: string + detail: + description: Detailed summary describing the particular error + type: string + type: + description: Reference that identifies the particular error + type: string + code: + description: Code representing the particular error + type: integer + format: int32 + errors: + type: object + additionalProperties: + type: string + required: + - status + - title + - type + '409': + description: Request has been rejected due to conflict with the current state of the target resource + content: + application/json: + schema: + title: ErrorResponse + type: object + properties: + status: + description: HTTP status code + type: integer + format: int32 + title: + description: Short summary describing the particular error + type: string + detail: + description: Detailed summary describing the particular error + type: string + type: + description: Reference that identifies the particular error + type: string + code: + description: Code representing the particular error + type: integer + format: int32 + errors: + type: object + additionalProperties: + type: string + required: + - status + - title + - type + '422': + description: Request has been rejected due to missing or invalid data + content: + application/json: + schema: + title: ErrorResponse + type: object + properties: + status: + description: HTTP status code + type: integer + format: int32 + title: + description: Short summary describing the particular error + type: string + detail: + description: Detailed summary describing the particular error + type: string + type: + description: Reference that identifies the particular error + type: string + code: + description: Code representing the particular error + type: integer + format: int32 + errors: + type: object + additionalProperties: + type: string + required: + - status + - title + - type + default: + description: Internal server error + content: + application/json: + schema: + title: ErrorResponse + type: object + properties: + status: + description: HTTP status code + type: integer + format: int32 + title: + description: Short summary describing the particular error + type: string + detail: + description: Detailed summary describing the particular error + type: string + type: + description: Reference that identifies the particular error + type: string + code: + description: Code representing the particular error + type: integer + format: int32 + errors: + type: object + additionalProperties: + type: string + required: + - status + - title + - type +components: + parameters: + Accept: + name: Accept + in: header + required: true + description: 'The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body.' + schema: + type: string + default: 'application/json' + ContentType: + name: Content-Type + in: header + required: true + description: 'The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the request body.' + schema: + type: string + default: 'application/json' + schemas: + Order: + title: Order + type: object + properties: + id: + description: Identifier for the order + type: integer + minimum: 1 + format: int32 + is_recurring: + description: Whether this is a recurring order. If the order is recurring this field should be set to true in order to let the payment gateway know. + example: false + type: boolean + default: false + required: + - id + x-examples: + example-1: + id: 1 + is_recurring: false + x-internal: false + securitySchemes: + X-Auth-Token: + name: X-Auth-Token + description: |- + ### OAuth scopes + + | UI Name | Permission | Parameter | + |:--------|:-----------|:----------| + | Create Payments | create | `store_payments_access_token_create` | + | Get Payment Methods | read-only | `store_payments_methods_read` | + + ### Authentication header + + | Header | Argument | Description | + |:-------|:---------|:------------| + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | + + ### Further reading + + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). + + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). + + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). + type: apiKey + in: header + diff --git a/reference/payment_methods.v2.yml b/reference/payments/methods_payments.v2.yml similarity index 60% rename from reference/payment_methods.v2.yml rename to reference/payments/methods_payments.v2.yml index 3ff2e4f09..614f50ff6 100644 --- a/reference/payment_methods.v2.yml +++ b/reference/payments/methods_payments.v2.yml @@ -1,8 +1,34 @@ openapi: '3.0.1' info: - title: Payment Methods - description: |- - Get a list of a store's enabled payment methods. For processing payments, see [Payment Processing API](/api-docs/payments/payments-api-overview). + title: Payment Methods (Deprecated) + description: | + > The Payments API processes payments using payment instruments such as credit cards or PayPal accounts. To learn more about Payments, see the [Payments Overview](/docs/store-operations/payments). + + This endpoint is deprecated. Use [Get accepted payment methods](/docs/rest-payments/methods#get-accepted-payment-methods) instead. + + The V3 version of this endpoint contains more information about the payment methods each payment gateway accepts. The additional information enables your application and BigCommerce to make the most likely-to-succeed payment request to the gateway, without using extra middleware or making preparatory API calls to the gateway on your end prior to running the payment. Use [Get accepted payment methods](/docs/rest-payments/methods#get-accepted-payment-methods) for a leaner, more optimized application. + + > To learn more about authenticating Payments endpoints, locate the **Authentication** section at the top of each endpoint, then click **Show Details**. + + ## Resources + + * [Payments Overview](/docs/store-operations/payments) + * [Process payments authentication example request](/docs/start/authentication#bigcommerce-generated-jwts) + * [Orders Overview](/docs/store-operations/orders) + + ### Webhooks + + * [Carts](https://developer.bigcommerce.com/api-docs/channels/guide/webhooks#carts) + * [Orders](https://developer.bigcommerce.com/api-docs/store-management/webhooks/webhook-events#orders) + * [Price list assignment](https://developer.bigcommerce.com/api-docs/channels/guide/webhooks#price-list-assignments) + + ### Payments endpoints + + * [Get accepted payment methods](/docs/rest-payments/methods#get-accepted-payment-methods) + * [Create a Payment Access Token](/docs/rest-payments/tokens#create-payment-access-token) + * [Process payments](/docs/rest-payments/processing#process-payment) + * [Get a customer's stored instruments](/docs/rest-management/customers/customer-stored-instruments#get-stored-instruments) + termsOfService: 'https://www.bigcommerce.com/terms' contact: name: BigCommerce @@ -19,18 +45,19 @@ servers: description: Permanent ID of the BigCommerce store. description: BigCommerce API Gateway security: -- X-Auth-Token: [] + - X-Auth-Token: [] tags: -- name: Payment Methods + - name: Methods (Deprecated) paths: '/payments/methods': parameters: - $ref: '#/components/parameters/Accept' get: tags: - - Payment Methods + - Methods (Deprecated) summary: Get All Payment Methods operationId: getAllPaymentMethods + deprecated: true description: | Gets the list of enabled payment methods. Default sorting is by payment method, alphabetically from A to Z. @@ -76,14 +103,6 @@ components: schema: type: string default: 'application/json' - ContentType: - name: Content-Type - in: header - required: true - description: 'The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the request body.' - schema: - type: string - default: 'application/json' schemas: payment_Base: title: payment_Base @@ -107,15 +126,6 @@ components: name: Square test_mode: false x-internal: false - responses: - paymentCollection_Resp: - description: "" - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/payment_Base' securitySchemes: X-Auth-Token: name: X-Auth-Token @@ -130,14 +140,14 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header diff --git a/reference/payments/process_payments.yml b/reference/payments/process_payments.yml new file mode 100644 index 000000000..30da26157 --- /dev/null +++ b/reference/payments/process_payments.yml @@ -0,0 +1,560 @@ +openapi: '3.0.0' +info: + version: '' + title: Payment Processing + description: | + > The Payments API processes payments using payment instruments such as credit cards or PayPal accounts. To learn more about Payments, see the [Payments Overview](/docs/store-operations/payments). + + The Payment Processing API uses BigCommerce's PCI-compliant payments server and a supported payment gateway to charge customers. The payment portal you choose may support charging stored instruments and/or making refund transactions. For a list of compatible payment gateways, as well as a guide through the API call sequence needed to make charges, see the [Payments Overview](/docs/store-operations/payments#compatible-payment-gateways). + + A Payment Access Token (_PAT_) is required to authorize payment processing requests. The X-Auth-Token header is not required in requests to the payment processing endpoint. To generate a PAT, use the [Create a Payment Access Token](/docs/rest-payments/tokens#create-payment-access-token) endpoint or the `completeCheckout` mutation in the [GraphQL Storefront API](/docs/storefront/cart-checkout/guide/graphql-storefront#handling-payments). For a payment processing authentication example request, see the related section in our [Authentication article](/docs/start/authentication#bigcommerce-generated-jwts). + + Also note that payment processing requests use the BigCommerce Payments Gateway, which uses a different server than our other REST APIs. Please see the server URL for the payment processing endpoint. + + > To learn more about authenticating Payments endpoints, locate the **Authentication** section at the top of each endpoint, then click **Show Details**. + + ## Resources + + * [Payments Overview](/docs/store-operations/payments) + * [Process payments authentication example request](/docs/start/authentication#bigcommerce-generated-jwts) + * [Orders Overview](/docs/store-operations/orders) + + ### Webhooks + + * [Carts](https://developer.bigcommerce.com/api-docs/channels/guide/webhooks#carts) + * [Orders](https://developer.bigcommerce.com/api-docs/store-management/webhooks/webhook-events#orders) + * [Price list assignment](https://developer.bigcommerce.com/api-docs/channels/guide/webhooks#price-list-assignments) + + ### Additional Payments endpoints + + * [Get accepted payment methods](/docs/rest-payments/methods#get-accepted-payment-methods) + * [Create a Payment Access Token](/docs/rest-payments/tokens#create-payment-access-token) + * [Get a customer's stored instruments](/docs/rest-management/customers/customer-stored-instruments#get-stored-instruments) + + + termsOfService: 'https://www.bigcommerce.com/terms' + contact: + name: BigCommerce + url: 'https://www.bigcommerce.com' + email: support@bigcommerce.com +tags: + - name: Processing +servers: + - url: 'https://payments.bigcommerce.com/stores/{store_hash}' + variables: + store_hash: + default: store_hash + description: Permanent ID of the BigCommerce store. + description: BigCommerce Payments Gateway +security: + - BearerPAT: [] +paths: + '/payments': + post: + summary: Process Payments + tags: + - Processing + operationId: PaymentsPost + description: 'Process payments for an order. See [Payment Processing](/docs/store-operations/payments) for more information.' + parameters: + - $ref: '#/components/parameters/AcceptPaymentResponse' + - $ref: '#/components/parameters/ContentType' + requestBody: + content: + application/json: + schema: + title: Payment Request + type: object + properties: + payment: + title: Payment + type: object + required: + - instrument + - payment_method_id + properties: + instrument: + anyOf: + - $ref: '#/components/schemas/Card' + - $ref: '#/components/schemas/StoredCard' + - $ref: '#/components/schemas/StoredPayPalAccount' + - $ref: '#/components/schemas/GiftCertificate' + - $ref: '#/components/schemas/StoreCredit' + - $ref: '#/components/schemas/TokenizedCard' + payment_method_id: + description: Identifier for payment method that will be used for this payment and `id` from the Get Accepted Payment Methods API + type: string + minLength: 1 + save_instrument: + type: boolean + description: 'To use `save_instrument`, configure the payment gateway to accept stored cards.' + required: + - payment + examples: + Card: + value: + payment: + instrument: + type: card + cardholder_name: string + number: string + expiry_month: 1 + expiry_year: 0 + verification_value: stri + issue_month: 1 + issue_year: 0 + issue_number: 0 + payment_method_id: string + Stored Card: + value: + payment: + instrument: + type: stored_card + token: 8cdf7b6ea1b27119463bf9e5106639618cc77a9adc49f0069ca8b756cc15caee + verification_value: '1142' + payment_method_id: adyenv2.scheme + save_instrument: true + Stored PayPal Account: + value: + payment: + instrument: + type: stored_paypal_account + token: 2c129313bcffe4501ec5fa2764c8c16320e38c7ba9e8cdf95583b541bb05ad91 + payment_method_id: braintree.paypal + Gift Certificate: + value: + payment: + instrument: + type: gift_certificate + gift_certificate_code: ABC-DEF-GXX + payment_method_id: bigcommerce.gift_certificate + Store Credit: + value: + payment: + instrument: + type: store_credit + payment_method_id: bigcommerce.store_credit + Tokenized Card: + value: + payment: + instrument: + type: tokenized_card + token: K7KW-M9GX-6PQ3 + iin: 4111111 + last_four_digits: 1111 + expiration_month: 12 + expiration_year: 2030 + payment_method_id: bolt.card + required: true + x-examples: + application/json: + payment: + instrument: {} + payment_method_id: Lorem in + amount: 81505146 + currency_code: NYE + Payment Access Token: |- + curl -X POST \ + https://payments.bigcommerce.com/stores/{store_hash}/payments \ + -H 'Accept: application/vnd.bc.v1+json' \ + -H 'Authorization: PAT eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1NsdfasftIsIm5iZiI6MTU1MTM5MDU0MiwiaXNzIjoicGF5bWVudHMuYmlnY29tbWVyY2UuY29tIiwic3ViIjoianJhaDZnbW4iLCJqdGkiOiI3Nzg3ZmU1Zi01OWJmLTQ3ZWMtYTFmZC00ZDQ3ZTkwNjFlNWMiLCJpYXQiOjE1NTEzOTA1NDIsImRhdGEiOnsic3RvcmVfaWQiOjEwMjU2NDYsIm9yZGVyX2lkIjoyMTUsImFtb3VudCI6OTgwMCwiY3VycmVuY3kiOiJVU0QifX0.WbR90d8m4gn8wK7kPMDEoVq8B0hHC5Ul5H4Hpqq6Yvo' \ + -H 'Content-Type: application/json' \ + Vaulted Card: + payment: + instrument: + type: stored_card + token: vaulted instrument token + verification_value: '123' + payment_method_id: stripe.card + save_instrument: true + Credit Card: |- + { + "payment": { + "instrument": { + "type": "card", + "number": "4111111111111111", + "cardholder_name": "BP", + "expiry_month": 12, + "expiry_year": 2020, + "verification_value": "411" + }, + "payment_method_id": "authorizenet.card", + "save_instrument": true + } + } + description: '' + responses: + '202': + description: Payment has been successfully processed + content: + application/json: + schema: + title: Success Payment Response + type: object + properties: + id: + description: Identifier for this transaction + type: string + transaction_type: + title: Transaction Type + description: Transaction type for this payment + example: authorization + type: string + enum: + - authorization + - purchase + status: + type: string + title: Status + description: Status to indicate a success response + enum: + - success + - pending + examples: + response: + value: + id: 227d9e1e-94f8-408c-95a5-f97b30592eb7 + transaction_type: authorization + status: pending + '400': + description: Payment request has been rejected due to malformed request + content: + application/json: + schema: + title: Error Payment Response + type: object + properties: + status: + description: HTTP status code + type: integer + format: int32 + title: + description: Short summary describing the particular error + type: string + detail: + description: Detailed summary describing the particular error + type: string + type: + description: Reference that identifies the particular error + type: string + code: + description: Code representing the particular error + type: integer + format: int32 + errors: + description: '' + type: object + additionalProperties: + type: string + required: + - status + - title + - type + '401': + description: Valid authentication required + content: + application/json: + schema: + title: Error Payment Response + type: object + properties: + status: + description: HTTP status code + type: integer + format: int32 + title: + description: Short summary describing the particular error + type: string + detail: + description: Detailed summary describing the particular error + type: string + type: + description: Reference that identifies the particular error + type: string + code: + description: Code representing the particular error + type: integer + format: int32 + errors: + description: '' + type: object + additionalProperties: + type: string + required: + - status + - title + - type + '422': + description: 'Payment request has been rejected due to missing, invalid data or declined by payment provider' + content: + application/json: + schema: + title: Error Payment Response + type: object + properties: + status: + description: HTTP status code + type: integer + format: int32 + title: + description: Short summary describing the particular error + type: string + detail: + description: Detailed summary describing the particular error + type: string + type: + description: Reference that identifies the particular error + type: string + code: + description: Code representing the particular error + type: integer + format: int32 + errors: + description: '' + type: object + additionalProperties: + type: string + required: + - status + - title + - type + default: + description: Internal server error + content: + application/json: + schema: + title: Error Payment Response + type: object + properties: + status: + description: HTTP status code + type: integer + format: int32 + title: + description: Short summary describing the particular error + type: string + detail: + description: Detailed summary describing the particular error + type: string + type: + description: Reference that identifies the particular error + type: string + code: + description: Code representing the particular error + type: integer + format: int32 + errors: + description: '' + type: object + additionalProperties: + type: string + required: + - status + - title + - type +components: + parameters: + AcceptPaymentResponse: + name: Accept + in: header + schema: + type: string + enum: + - 'application/vnd.bc.v1+json' + default: 'application/vnd.bc.v1+json' + required: true + description: This required value must be `application/vnd.bc.v1+json`. + ContentType: + name: Content-Type + in: header + required: true + description: 'The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the request body.' + schema: + type: string + default: 'application/json' + schemas: + Card: + title: Card + type: object + x-examples: + example-1: + type: card + cardholder_name: string + number: string + expiry_month: 1 + expiry_year: 0 + verification_value: stri + issue_month: 1 + issue_year: 0 + issue_number: 0 + x-internal: false + properties: + type: + type: string + default: card + example: card + description: Type to classify this payment instrument (required) + cardholder_name: + type: string + minLength: 1 + description: Cardholderʼs full name (required) + number: + type: string + minLength: 1 + description: Credit card number (required) + expiry_month: + type: integer + format: int32 + minimum: 1 + maximum: 12 + description: Expiry month of this card (required) + expiry_year: + type: integer + format: int32 + description: Expiry year of this card (required) + verification_value: + type: string + minLength: 3 + maxLength: 4 + description: Verification value of this card (CVV) + issue_month: + type: integer + description: Issue month of this card + format: int32 + minimum: 1 + maximum: 12 + issue_year: + type: integer + format: int32 + description: Issue year of this card + issue_number: + type: integer + format: int32 + description: Issue number of this card + StoredCard: + title: Stored Card + type: object + x-internal: false + x-examples: + example-1: + type: stored_card + token: stringstringstringstringstringstringstringstringstringstringstri + verification_value: 1142 + properties: + type: + description: Type to classify this payment instrument (required) + example: stored_card + type: string + default: stored_card + token: + description: Identifier representing this stored card (required) + type: string + minLength: 64 + maxLength: 64 + verification_value: + type: string + description: Verification value of this card (CVV) + minLength: 3 + maxLength: 4 + StoredPayPalAccount: + title: StoredPayPalAccount + type: object + x-internal: false + properties: + type: + type: string + description: Type to classify this payment instrument (required) + enum: + - stored_paypal_account + token: + description: Identifier representing this stored PayPal account (required) + type: string + minLength: 64 + maxLength: 64 + x-examples: + example-1: + type: stored_paypal_account + token: stringstringstringstringstringstringstringstringstringstringstri + GiftCertificate: + title: GiftCertificate + type: object + properties: + type: + type: string + example: gift_certificate + gift_certificate_code: + type: string + example: ABC-DEF-GXX + x-examples: + example-1: + type: gift_certificate + gift_certificate_code: ABC-DEF-GXX + StoreCredit: + title: StoreCredit + type: object + properties: + type: + type: string + example: store_credit + x-examples: + example-1: + type: store_credit + TokenizedCard: + title: Tokenized Card + type: object + x-internal: false + x-examples: + example-1: + type: tokenized_card + token: K7KW-M9GX-6PQ3 + iin: 4111111 + last_four_digits: 1111 + expiration_month: 12 + expiration_year: 2030 + properties: + type: + type: string + description: Type to classify this payment instrument (required). + enum: + - tokenized_card + token: + description: Identifier representing the tokenized card (required). + type: string + minLength: 64 + maxLength: 64 + iin: + type: string + description: Issuer identification number. + last_four_digits: + type: string + description: Last four numbers of this card. + expiration_month: + type: string + description: Expiry month of this card. + expiration_year: + type: string + description: Expiry year of this card. + required: + - type + - token + securitySchemes: + BearerPAT: + description: |- + ### OAuth scopes + + The required scopes are granted to the `payment_access_token` upon generation. + + ### Authentication header + + | Header | Argument | Description | + |:-------|:---------|:------------| + |`Authorization`|`PAT {{PAYMENT_ACCESS_TOKEN}}`| Obtained using the Create Access Token endpoint.| + + ### Further reading + + For an outline of the Process Payment API call flow and more information about authenticating, see [Authentication and Example Requests](/docs/start/authentication#bigcommerce-generated-jwts). + + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). + type: http + scheme: bearer + bearerFormat: 'PAT {{PAYMENT_ACCESS_TOKEN}}' diff --git a/reference/price_lists.v3.yml b/reference/price_lists.v3.yml index 95fa56b7b..38832d3aa 100644 --- a/reference/price_lists.v3.yml +++ b/reference/price_lists.v3.yml @@ -5,50 +5,49 @@ info: Populate different versions of catalog pricing and assign them to different [customer groups](/docs/rest-management/customers-v2/customer-groups) at the variant level. ## Price Lists - You can associate a Price List with a customer group either through the control panel or by using the [Customer Groups API](/docs/rest-management/customers-v2/customer-groups). You can create [Price List Assignments](/docs/rest-management/price-lists/price-lists-assignments#create-price-list-assignments) to assign Price Lists to a specific [channel](/docs/rest-management/channels/channel-listings). Price Lists assigned to a channel apply to all shoppers on that channel, unless there are more specific assignments or customer group discounts set up for the shopper's customer group. If an active Price List does not contain prices for a variant, the catalog pricing will be used. + Price Lists provide overridden price values to the Stencil storefront. You can further customize the final price display using Stencil's [handlebars objects](/docs/storefront/stencil/themes/context/object-reference/config). - Price Lists provide overridden price values to the Stencil storefront. You can further customize the final price display using Stencil's [handlebars objects](/theme-objects). - - To learn more about Price Lists, see [Price Lists API](/api-docs/store-management/price-list-overview). + To learn more about Price Lists, see [Price Lists API](/docs/store-operations/pricing/price-lists). ## Price Lists Assignments ### Order of operations - + **IF** Price List assigned to current customer group **AND** Price List assigned to current channel: * Use this Price List -- any prices not found fall back to the catalog price (or in the case of multi-currency, auto-converted prices) - + **ELSE IF** Price List assigned to current customer group: * Use this Price List -- any prices not found fall back to the catalog price (or in the case of multi-currency, auto-converted prices) - + **ELSE IF** Customer group discounts: * Use them -- any prices not found fall back to the catalog price (or in the case of multi-currency, auto-converted prices) - + **ELSE IF** Channel has a default Price List: * Use this Price List -- any prices not found fall back to the catalog price (or in the case of multi-currency, auto-converted prices) - + **ELSE**: * Fall back to the catalog price (or in the case of multi-currency, auto-converted prices) ## Usage notes - - Price Lists cannot be assigned to a customer group that has customer group discounts -- the customer group discounts must be deleted first. - - Bulk pricing Tiers may additionally be associated with a price record to indicate different pricing as the quantity in the cart increases. - - If a variant has a Price Record, any existing product-level bulk pricing will not apply in the cart. For variants without Price Records, any existing product bulk pricing will apply. - - [Price Lists Records](/docs/rest-management/price-lists/price-lists-records) accepts bulk upsert. You can only do one bulk upsert at a time. Running more than one bulk upsert in parallel on the **same store** will cause a 429 error and the request will fail. - - There are no webhooks available for Price Lists. Since Price Lists directly relate to products, product webhooks will trigger for corresponding changes such as pricing. + + - You cannot assign Price Lists to a customer group with customer group discounts -- You must delete the customer group discounts first. + - Bulk pricing Tiers can additionally be associated with a price record to indicate different pricing as the quantity in the cart increases. + - If a variant has a Price Record, any existing product-level bulk pricing will not apply to the cart. For variants without Price Records, any existing product bulk pricing will apply. + - [Price Lists Records](/docs/rest-management/price-lists/price-lists-records) accepts bulk upsert. You can only do one bulk upsert at a time. Running more than one bulk upsert in parallel on the **same store** will cause a `429` error and the request will fail. + - There are webhooks available for Price Lists assignments. The price list assignment webhook fires when a price list assignment is assigned, reassigned, or unassigned. Note that since Price Lists directly relate to products, neither product nor SKU webhooks are going to fire for corresponding changes, such as pricing. ## Additional information ### Webhooks - - * [Products](/api-docs/store-management/webhooks/events#products) - * [SKU](/api-docs/store-management/webhooks/events#sku) - + + * [Price list assignments](/docs/integrations/webhooks/events/channels#price-list-assignments) + * [Products](/docs/integrations/webhooks/events#products) + * [SKU](/docs/integrations/webhooks/events#sku) ### Related endpoints * [Get All Price Lists](/docs/rest-management/price-lists#get-all-price-lists) termsOfService: 'https://www.bigcommerce.com/terms' @@ -68,7 +67,6 @@ security: - X-Auth-Token: [] tags: - name: Price Lists - description: BigCommerce Price Lists API Definition. - name: Price Lists Assignments - name: Price Lists Records paths: @@ -432,7 +430,6 @@ paths: The error title describing the particular error. type: type: string - x-codegen-request-body-name: PriceList delete: tags: - Price Lists @@ -747,14 +744,12 @@ paths: The error title describing the particular error. type: type: string - x-codegen-request-body-name: PriceList delete: tags: - Price Lists summary: Delete a Price List description: |- Deletes a *Price List*. All associated price records are also removed. - **Limits** * Limit of 1 concurrent request. operationId: deletePriceList @@ -769,6 +764,37 @@ paths: responses: '204': description: Action has been enacted and no further information is to be supplied. `null` is returned. + '/pricelists/records': + parameters: + - $ref: '#/components/parameters/Accept' + put: + tags: + - Price Lists Records + summary: Create Batch of Price Lists Records + description: Creates a batch of `Price Lists Records`; may include price list records from more than one price list. Concurrency limit of 1. + operationId: UpsertPriceListRecords + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PriceRecordCollectionPutWithPriceListId' + required: true + responses: + '200': + description: | + Success response for batch PUT of `Price Records`. + content: + application/json: + schema: + $ref: '#/components/schemas/SuccessBatchResponse' + '422': + description: | + Error response for batch PUT of `Price Records`. May include errors during partial update in non-strict mode. + content: + application/json: + schema: + $ref: '#/components/schemas/PriceRecordBatchErrorResponse' + x-codegen-request-body-name: PriceRecordBatch '/pricelists/{price_list_id}/records': parameters: - $ref: '#/components/parameters/Accept' @@ -823,11 +849,14 @@ paths: in: query description: | Sub-resources to include on a price record, in a comma-separated list. Valid expansions currently include `bulk_pricing_tiers` and `sku`. Other values will be ignored. + explode: false schema: - type: string - enum: - - bulk_pricing_tiers - - sku + type: array + items: + type: string + enum: + - bulk_pricing_tiers + - sku - name: price in: query description: | @@ -973,6 +1002,7 @@ paths: The price of the variant as seen on the storefront if a price record is in effect. It will be equal to the `sale_price`, if set, and the `price` if there is not a `sale_price`. Read only. format: double example: 24.64 + readOnly: true date_created: type: string description: | @@ -988,8 +1018,9 @@ paths: product_id: type: integer description: | - The id of the `Product` this `Price Record`'s variant_id is associated with. Read only. + The ID of the `Product` this `Price Record`ʼs `variant_id` is associated with. Read only. example: 158 + readOnly: true - title: Price Record Identifiers type: object description: Price Record object used in batch create or update. @@ -1004,12 +1035,12 @@ paths: variant_id: type: integer description: | - The variant with which this price set is associated. Either variant_id or SKU is required. + The variant with which this price set is associated. Either `variant_id` or `sku` is required. example: 325 sku: type: string description: | - The variant with which this price set is associated. Either SKU or variant_id is required. + The variant with which this price set is associated. Either `sku` or `variant_id` is required. currency: type: string description: | @@ -1373,21 +1404,33 @@ paths: per_page: 50 current_page: 1 total_pages: 1 + '429': + description: | + Allowed number of requests exceeded. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + response: + value: + status: 429 + title: Too many requests + type: /api-docs/getting-started/api-status-codes + errors: {} + examples: {} put: tags: - Price Lists Records summary: Upsert Price List Records description: |- Creates or updates *Price List Records*. - **Required Fields** * currency - **Notes** - - * Batch updates are supported by this endpoint, meaning that several price objects can be updated in one request. This allows you to do the same work as many individual requests to singleton endpoints * Batch requests support up to 1,000 items per request. - * Up to 2 concurrent batch upsert requests are supported with this API. Running more than the allowed concurrent requests in parallel on the **same store** will cause a 429 error and your additional requests will fail. You are encouraged to run requests sequentially with as many records per request as possible, in order to maximize performance. + * Up to 2 concurrent batch upsert requests are supported with this API. Running more than the allowed concurrent requests in parallel on the **same store** will cause a `429` error, and your additional requests will fail. You are encouraged to run requests sequentially with as many records per request as possible to maximize performance. + * When updating a product with variants, or multiple SKUs, don't include records for the parent product SKU. operationId: setPriceListRecordCollection parameters: - name: price_list_id @@ -1397,13 +1440,6 @@ paths: required: true schema: type: integer - - name: X-Strict-Mode - in: header - description: | - Header that determines whether the Batch API operates in strict mode or not. Strict mode will reject the entire request if any item in the batch has an error. - schema: - type: integer - default: 0 - $ref: '#/components/parameters/ContentType' requestBody: content: @@ -1419,12 +1455,12 @@ paths: variant_id: type: integer description: | - The variant ID with which this price set is associated. Either variant_id or SKU is required. + The variant ID with which this price set is associated. Either `variant_id` or `sku` is required. example: 331 sku: type: string description: | - The SKU for the variant with which this price set is associated. Either SKU or variant_id is required. + The SKU for the variant with which this price set is associated. Either `sku` or `variant_id` is required. example: SMB-123 currency: type: string @@ -1505,56 +1541,19 @@ paths: description: '' responses: '200': - description: Success response for batch PUT requests of Price Records. + description: 'Success response for batch PUT requests of Price Records.' content: application/json: schema: - type: array - items: - type: object - properties: - variant_id: - type: integer - sku: - type: string - currency: - type: string - price: - type: number - sale_price: - type: integer - retail_price: - type: integer - map_price: - type: integer - bulk_pricing_tiers: - type: array - items: - type: object - properties: - quantity_min: - type: integer - quantity_max: - type: integer - type: - type: string - amount: - type: integer - x-examples: - example-1: - - variant_id: 331 - sku: SMB-123 - currency: usd - price: 3.99 - sale_price: 3.49 - retail_price: 4.99 - map_price: 2.5 - bulk_pricing_tiers: - - quantity_min: 1 - quantity_max: 10 - type: fixed - amount: 3 - examples: {} + title: Price Records response + type: object + properties: + data: + type: object + properties: {} + meta: + type: object + properties: {} '422': description: Error response for batch PUT of `Price Records`. May include errors during partial update in non-strict mode. content: @@ -1584,12 +1583,12 @@ paths: variant_id: type: integer description: | - The variant ID with which this price set is associated. Either variant_id or SKU is required. + The variant ID with which this price set is associated. Either `variant_id` or `sku` is required. example: 325 sku: type: string description: | - The variant with which this price set is associated. Either SKU or variant_id is required. + The variant with which this price set is associated. Either `sku` or `variant_id` is required. currency: type: string description: | @@ -1603,6 +1602,21 @@ paths: additionalProperties: true description: Error during Price Record batch PUT request. Includes data sent in the request and errors. description: Errors during batch usage for the BigCommerce API. + '429': + description: | + Allowed number of requests exceeded. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + response: + value: + status: 429 + title: Too many requests + type: /api-docs/getting-started/api-status-codes + errors: {} + examples: {} delete: tags: - Price Lists Records @@ -1654,7 +1668,7 @@ paths: Returns *Price List Records* using the variant ID. Will also contain currency records. **Notes** - * Supports up to 50 simultaneous GET requests. Running more than the allowed number of requests concurrently on the same store will result in a `429` status error and your additional requests will fail. + * Supports up to 40 simultaneous GET requests. Running more than the allowed number of requests concurrently on the same store will result in a `429` status error, and your additional requests will fail. * Store Pricelist Records data to reduce the number of calls and maximize performance. operationId: getPriceListRecordsByVariantId parameters: @@ -1698,6 +1712,7 @@ paths: The price of the variant as seen on the storefront if a price record is in effect. It will be equal to the `sale_price`, if set, and the `price` if there is not a `sale_price`. Read only. format: double example: 24.64 + readOnly: true date_created: type: string description: | @@ -1713,8 +1728,9 @@ paths: product_id: type: integer description: | - The id of the `Product` this `Price Record`'s variant_id is associated with. Read only. + The ID of the `Product` this `Price Record`ʼs `variant_id` is associated with. Read only. example: 158 + readOnly: true - title: Price Record Identifiers description: Price Record object used in batch create or update. properties: @@ -1726,12 +1742,12 @@ paths: variant_id: type: integer description: | - The variant ID with which this price set is associated. Either variant_id or SKU is required. + The variant ID with which this price set is associated. Either `variant_id` or `sku` is required. example: 325 sku: type: string description: | - The variant ID with which this price set is associated. Either SKU or variant_id is required. + The variant ID with which this price set is associated. Either `sku` or `variant_id` is required. currency: type: string description: | @@ -1859,7 +1875,21 @@ paths: type: string description: | Link to the next page returned in the response. - examples: {} + '429': + description: | + Allowed number of requests exceeded. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + response: + value: + status: 429 + title: Too many requests + type: /api-docs/getting-started/api-status-codes + errors: {} + examples: {} '/pricelists/{price_list_id}/records/{variant_id}/{currency_code}': parameters: - $ref: '#/components/parameters/Accept' @@ -1867,7 +1897,10 @@ paths: tags: - Price Lists Records summary: Get a Price Record by Currency Code - description: Returns a *Price List Record* using the currency code. Optional parameters can be used. + description: |- + Returns a *Price List Record* using the currency code. You can use optional parameters. + **Notes** + * Supports up to 50 simultaneous GET requests. Running more than the allowed number of requests concurrently on the same store will result in a `429` status error, and your additional requests will fail. operationId: getPriceListRecord parameters: - name: price_list_id @@ -1895,12 +1928,16 @@ paths: - name: include in: query description: | - Sub-resources to include on a price record, in a comma-separated list. Valid expansions currently include `bulk_pricing_tiers` and `sku`. Other valies will be ignored. + Sub-resources to include on a price record, in a comma-separated list. Valid expansions currently include `bulk_pricing_tiers` and `sku`. Other values will be ignored. + Sub-resources to include on a price record, in a comma-separated list. Valid expansions currently include `bulk_pricing_tiers` and `sku`. Other values will be ignored. + explode: false schema: - type: string - enum: - - bulk_pricing_tiers - - sku + type: array + items: + type: string + enum: + - bulk_pricing_tiers + - sku responses: '200': description: '' @@ -1923,6 +1960,7 @@ paths: The price of the variant as seen on the storefront if a price record is in effect. It will be equal to the `sale_price`, if set, and the `price` if there is not a `sale_price`. Read only. format: double example: 24.64 + readOnly: true date_created: type: string description: | @@ -1938,8 +1976,9 @@ paths: product_id: type: integer description: | - The ID of the `Product` this `Price Record`'s variant_id is associated with. Read only. + The ID of the `Product` this `Price Record`ʼs `variant_id` is associated with. Read only. example: 158 + readOnly: true - title: Price Record Identifiers type: object description: Price Record object used in batch create or update requests. @@ -1954,12 +1993,12 @@ paths: variant_id: type: integer description: | - The variant with which this price set is associated. Either variant_id or SKU is required. + The variant with which this price set is associated. Either `variant_id` or `sku` is required. example: 325 sku: type: string description: | - The variant with which this price set is associated. Either SKU or variant_id is required. + The variant with which this price set is associated. Either `sku` or `variant_id` is required. currency: type: string description: | @@ -2052,11 +2091,29 @@ paths: per_page: 50 current_page: 1 total_pages: 1 + '429': + description: | + Allowed number of requests exceeded. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + response: + value: + status: 429 + title: Too many requests + type: /api-docs/getting-started/api-status-codes + errors: {} + examples: {} put: tags: - Price Lists Records summary: Set Price List Record by Currency Code - description: Creates or updates a*Price List Record* using the currency code. + description: |- + Creates or updates a *Price List Record* using the currency code. + **Notes** + * Supports up to 40 simultaneous PUT requests. Running more than the allowed number of requests concurrently on the same store will result in a `429` status error, and your additional requests will fail. operationId: setPriceListRecord parameters: - name: price_list_id @@ -2171,6 +2228,7 @@ paths: description: | The price of the variant as seen on the storefront if a price record is in effect. It will be equal to the `sale_price`, if set, and the `price` if there is not a `sale_price`. Read only. example: 24.64 + readOnly: true date_created: type: string format: date-time @@ -2186,8 +2244,9 @@ paths: product_id: type: integer description: | - The id of the `Product` this `Price Record`'s variant_id is associated with. Read only. + The ID of the `Product` this `Price Record`ʼs `variant_id` is associated with. Read only. example: 158 + readOnly: true - description: Price Record object used in a batch create or update request. allOf: - properties: @@ -2199,12 +2258,12 @@ paths: variant_id: type: integer description: | - The variant with which this price set is associated. Either variant_id or SKU is required. + The variant with which this price set is associated. Either `variant_id` or `sku` is required. example: 325 sku: type: string description: | - The variant with which this price set is associated. Either SKU or variant_id is required. + The variant with which this price set is associated. Either `sku` or `variant_id` is required. currency: type: string format: ISO-4217 @@ -2379,12 +2438,29 @@ paths: The error title describing the particular error. type: type: string - x-codegen-request-body-name: PriceRecord + '429': + description: | + Allowed number of requests exceeded. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + response: + value: + status: 429 + title: Too many requests + type: /api-docs/getting-started/api-status-codes + errors: {} + examples: {} delete: tags: - Price Lists Records summary: Delete a Price Record by Currency Code - description: Deletes a *Price List Record* using the currency code. + description: |- + Deletes a *Price List Record* using the currency code. + **Note:** + * Supports up to 25 simultaneous DELETE requests. Running more than the allowed number of requests concurrently on the same store will result in a `429` status error, and your additional requests will fail. operationId: deletePriceListRecord parameters: - name: price_list_id @@ -2501,7 +2577,6 @@ paths: - Price Lists Assignments description: |- Creates a batch of `Price List Assignments`. - **Note:** The batch limit for `Price List Assignments` is 25. summary: Create Price List Assignments operationId: CreatePriceListAssignments @@ -2547,7 +2622,10 @@ paths: put: tags: - Price Lists Assignments - description: Upsert a single `Price List Assignment` for a `Price List`. + description: |- + Upsert a single `Price List Assignment` for a `Price List`. + **Note:** + * Supports up to 25 simultaneous PUT requests. Running more than the allowed number of requests concurrently on the same store will result in a `429` status error and your additional requests will fail. summary: Upsert Price List Assignment operationId: upsertPriceListAssignment parameters: @@ -2576,137 +2654,6 @@ components: description: Filter results by a comma-separated list of `channel_id`s. schema: type: string - FilterIdParam: - name: id - description: | - Filter items by id. - required: false - in: query - schema: - type: integer - FilterSkuParam: - name: sku - description: | - Filter items by SKU. - required: false - in: query - schema: - type: string - FilterProductIdParam: - schema: - type: string - name: 'product_id:in' - in: query - required: false - description: | - A comma-separated list of IDs of `Product`s for which prices were requested. - FilterNameParam: - name: name - description: | - Filter items by name. - required: false - in: query - schema: - type: string - FilterPriceParam: - name: price - description: | - Filter items by price. - required: false - in: query - schema: - type: number - FilterSalePriceParam: - name: sale_price - description: | - Filter items by sale_price. - required: false - in: query - schema: - type: number - FilterRetailPriceParam: - name: retail_price - description: | - Filter items by retail_price. - required: false - in: query - schema: - type: number - FilterMapPriceParam: - name: map_price - description: | - Filter items by map_price. - required: false - in: query - schema: - type: number - FilterCalculatedPriceParam: - name: calculated_price - description: | - Filter items by calculated_price. - required: false - in: query - schema: - type: number - VariantIdParam: - name: variant_id - in: path - description: | - ID of the variant on a product, or on an associated Price List Record. - required: true - schema: - type: integer - FilterDateModifiedParam: - name: date_modified - description: 'Filter items by date_modified. For example `v3/catalog/products?date_last_imported:min=2022-06-15`' - required: false - in: query - schema: - type: string - format: date-time - FilterDateCreatedParam: - name: date_created - description: | - Filter items by date_created. - required: false - in: query - schema: - type: string - format: date-time - FilterIncludePriceRecordParam: - name: include - description: | - Sub-resources to include on a price record, in a comma-separated list. Valid expansions currently include `bulk_pricing_tiers` and `sku`. Other values will be ignored. - required: false - in: query - schema: - type: string - enum: - - bulk_pricing_tiers - - sku - FilterCurrencyParam: - name: currency - description: | - Filter items by currency. - required: false - in: query - schema: - type: string - format: ISO-4217 - PageParam: - name: page - description: Specifies the page number in a limited (paginated) list of products. - required: false - in: query - schema: - type: integer - LimitParam: - name: limit - description: Controls the number of items per page in a limited (paginated) list of products. - required: false - in: query - schema: - type: integer PriceListIdParam: schema: type: integer @@ -2715,22 +2662,6 @@ components: description: | The ID of the `Price List` requested. required: true - PriceRecordCurrencyParam: - name: currency_code - in: path - description: | - The currency code associated with the price record being acted upon. - required: true - schema: - type: string - format: ISO-4217 - FilterVariantIdParam: - schema: - type: integer - name: 'variant_id:in' - in: query - required: false - description: The ID of the `Variant` for which prices were requested. Accept: name: Accept in: header @@ -2842,6 +2773,114 @@ components: example: 2 meta: $ref: '#/components/schemas/Meta' + PriceRecordCollectionPutWithPriceListId: + type: array + items: + $ref: '#/components/schemas/PriceRecordBatchItem' + PriceRecordBatchItem: + description: The `Price Record` object used in batch create or update. + allOf: + - type: array + items: + $ref: '#/components/schemas/PriceRecordBase' + properties: + price_list_id: + type: integer + description: The price list ID the price record is associated with. + variant_id: + type: integer + description: The price list with which the price record is associated. Either `variant_id` or `sku` is required. + sku: + type: string + description: The SKU for the variant with which this price record is associated. Either `sku` or `variant_id` is required. + currency: + type: string + description: The 3-letter country code with which this price record is associated. + format: ISO:4217 + PriceRecordBase: + type: object + properties: + price: + type: number + description: The list price for the variant mapped in a Price List. Overrides any existing or Catalog list price for the variant/product. If empty, the sale price will be treated as not being set on this variant. + + format: double + sale_price: + type: number + description: The sale price for the variant mapped in a Price List. Overrides any existing or Catalog sale price for the variant/product. If empty, the sale price will be treated as not being set on this variant. + format: double + retail_price: + type: number + description: The retail price for the variant mapped in a Price List. Overrides any existing or Catalog retail price for the variant/product. If empty, the retail price will be treated as not being set on this variant. + format: double + map_price: + type: number + description: The MAP (Minimum Advertised Price) for the variant mapped in a Price List. Overrides any existing or Catalog MAP price for the variant/product. If empty, the `map_ price` will be treated as not being set on this variant. + format: double + bulk_pricing_tiers: + type: array + items: + $ref: '#/components/schemas/BulkPricingTier' + description: Common Price Record properties. + BulkPricingTier: + type: object + properties: + quantity_min: + type: integer + description: The cart's minimum quantity of associated variants needed to qualify for this tier's pricing. + quantity_max: + type: integer + description: The cart's maximum allowed quantity of associated variants to qualify for this tier's pricing. + type: + type: string + description: |- + The type of adjustment that is made. + Acceptable values: + * price – the adjustment amount per product + * percent – the adjustment as a percentage of the original price + * fixed – the adjusted absolute price of the product + enum: + - fixed + - price + - percent + amount: + type: number + description: The price adjustment amount. This value and the type will decide the price per variant for the pricing tier. + format: double + SuccessBatchResponse: + type: object + description: Empty object for Success case for Batch API. + PriceRecordBatchErrorResponse: + type: object + properties: + data: + $ref: '#/components/schemas/PriceRecordIdentifiers' + field_errors: + $ref: '#/components/schemas/DetailedErrors' + description: Error during `Price Record` batch PUT. Includes data sent in the request and errors. + PriceRecordIdentifiers: + type: object + description: The `Price Record` object used in batch create or update. + allOf: + - type: object + properties: + price_list_id: + type: integer + description: The Price List with which this price record is associated. + variant_id: + type: integer + description: The variant with which this price record is associated. Either `variant_id` or `sku` is required. + sku: + type: string + description: The variant with which this price record is associated. Either `sku` or `variant_id` is required. + currency: + type: string + description: The 3-letter currency code with which this price set is associated. + format: ISO-4217 + DetailedErrors: + type: object + additionalProperties: + type: string PriceListAssignmentsBatchErrorResponse: type: object x-internal: false @@ -2897,1146 +2936,6 @@ components: meta: $ref: '#/components/schemas/CollectionMeta' x-internal: false - PriceListCollectionResponse: - description: Get All PriceLists. - type: object - properties: - data: - type: array - items: - allOf: - - properties: - id: - type: integer - description: | - The unique numeric ID of the `Price List`; this number increments sequentially. - example: 3 - date_created: - type: string - format: date-time - description: | - The date on which the `Price List` was created. - example: '2022-04-05T16:05:12Z' - date_modified: - type: string - format: date-time - description: | - The date on which the `Price List` was created. - example: '2022-04-05T16:05:12Z' - - type: object - description: Common Price List properties. - title: PriceList Base - properties: - name: - type: string - description: | - The unique name of the Price List. Required in a POST request. - x-required: - - post - example: Wholesale - active: - type: boolean - description: | - Whether or not this `Price List` and its prices are active. Defaults to `true`. - example: true - required: - - name - title: Price List - type: object - meta: - type: object - description: 'Data about the response, including pagination and collection totals.' - properties: - pagination: - type: object - description: 'Data about the response, including pagination and collection totals.' - title: Pagination - properties: - total: - type: integer - description: | - Total number of items in the result set. - example: 36 - count: - type: integer - description: | - Total number of items in the collection response. - example: 36 - per_page: - type: integer - description: | - The amount of items returned in the collection per page, controlled by the limit parameter. - example: 50 - current_page: - type: integer - description: | - The page you are currently on within the collection. - example: 1 - total_pages: - type: integer - description: | - The total number of pages in the collection. - example: 1 - links: - type: object - description: | - Pagination links for the previous and next parts of the whole collection. - properties: - previous: - type: string - description: | - Link to the previous page returned in the response. - current: - type: string - description: | - Link to the current page returned in the response. - example: '?page=1&limit=50' - next: - type: string - description: | - Link to the next page returned in the response. - title: Collection Meta - title: PriceList Collection Response - x-internal: false - PriceListResponse: - description: |- - PriceList Response returns for: - - * Create a PriceList - * Get a PriceList - * Update a PriceList - type: object - properties: - data: - allOf: - - properties: - id: - type: integer - description: | - The unique numeric ID of the `Price List`; increments sequentially. - example: 3 - date_created: - type: string - format: date-time - description: | - The date on which the `Price List` was created. - example: '2022-04-05T16:05:12Z' - date_modified: - type: string - format: date-time - description: | - The date on which the `Price List` was created. - example: '2022-04-05T16:05:12Z' - - type: object - description: Common Price List properties. - title: PriceList Base - properties: - name: - type: string - description: | - The unique name of the Price List. Required in a POST request. - x-required: - - post - example: Wholesale - active: - type: boolean - description: | - Whether or not this `Price List` and its prices are active. Defaults to `true`. - example: true - required: - - name - title: Price List - type: object - meta: - $ref: '#/components/schemas/Meta' - title: Price List Response - x-internal: false - PriceListBase: - type: object - description: Common Price List properties. - title: PriceList Base - properties: - name: - type: string - description: | - The unique name of the Price List. Required in a POST request. - x-required: - - post - example: Wholesale - active: - type: boolean - description: | - Whether or not this `Price List` and its prices are active. Defaults to `true`. - example: true - required: - - name - x-internal: false - PriceList: - allOf: - - properties: - id: - type: integer - description: | - The unique numeric ID of the `Price List`; increments sequentially. - example: 3 - date_created: - type: string - format: date-time - description: | - The date on which the `Price List` was created. - example: '2022-04-05T16:05:12Z' - date_modified: - type: string - format: date-time - description: | - The date on which the `Price List` was created. - example: '2022-04-05T16:05:12Z' - - type: object - description: Common Price List properties. - title: PriceList Base - properties: - name: - type: string - description: | - The unique name of the Price List. Required in a POST request. - x-required: - - post - example: Wholesale - active: - type: boolean - description: | - Whether or not this `Price List` and its prices are active. Defaults to `true`. - example: true - required: - - name - title: Price List - type: object - x-internal: false - PriceListPost: - type: object - allOf: - - type: object - description: Common Price List properties. - title: PriceList Base - properties: - name: - type: string - description: | - The unique name of the Price List. Required in a POST request. - x-required: - - post - example: Wholesale - active: - type: boolean - description: | - Whether or not this `Price List` and its prices are active. Defaults to `true`. - example: true - required: - - name - required: - - name - title: PriceList Post - description: 'Creates a Price List. ' - x-internal: false - PriceListPut: - type: object - allOf: - - type: object - description: Common Price List properties. - title: PriceList Base - properties: - name: - type: string - description: | - The unique name of the Price List. Required in a POST request. - x-required: - - post - example: Wholesale - active: - type: boolean - description: | - Whether or not this `Price List` and its prices are active. Defaults to `true`. - example: true - required: - - name - title: PriceList Put - description: Update a PriceList - x-internal: false - PriceRecordCollectionResponse: - description: |- - PriceRecord Collection Response returns for: - * Get All PriceList Records - * Get PriceList Records by Variant Id - type: object - properties: - data: - type: array - items: - description: The Price Record object. - allOf: - - properties: - calculated_price: - type: number - format: double - description: | - The price of the variant as seen on the storefront if a price record is in effect. It will be equal to the `sale_price`, if set, and the `price` if there is not a `sale_price`. Read only. - example: 24.64 - date_created: - type: string - format: date-time - description: | - The date on which the Price entry was created. - example: '2022-08-23T19:59:23Z' - date_modified: - type: string - format: date-time - description: | - The date on which the Price entry was created. - example: '2022-08-23T19:59:23Z' - product_id: - type: integer - description: | - The id of the `Product` this `Price Record`'s variant_id is associated with. Read only. - example: 158 - - description: Price Record object used in batch create or update. - allOf: - - properties: - price_list_id: - type: integer - description: | - The Price List with which this price set is associated. - example: 2 - variant_id: - type: integer - description: | - The variant ID with which this price set is associated. Either variant_id or SKU is required. - example: 325 - sku: - type: string - description: | - The SKU with which this price set is associated. Either SKU or variant_id is required. - currency: - type: string - format: ISO-4217 - description: | - The 3-letter currency code with which this price set is associated. - example: usd - title: Price Record Identifiers - type: object - - type: object - description: Common Price Record properties. - title: PriceRecord Base - properties: - price: - type: number - format: double - description: | - The list price for the variant mapped in a Price List. Overrides any existing or Catalog list price for the variant/product. - x-required: - - put - example: 3.99 - sale_price: - type: number - format: double - description: | - The sale price for the variant mapped in a Price List. Overrides any existing or Catalog sale price for the variant/product. If empty, the sale price will be treated as not being set on this variant. - retail_price: - type: number - format: double - description: | - The retail price for the variant mapped in a Price List. Overrides any existing or Catalog retail price for the variant/product. If empty, the retail price will be treated as not being set on this variant. - map_price: - type: number - format: double - description: | - The MAP (Minimum Advertised Price) for the variant mapped in a Price List. Overrides any existing or Catalog MAP price for the variant/product. If empty, the MAP price will be treated as not being set on this variant. - bulk_pricing_tiers: - type: array - items: - type: object - title: Bulk Pricing Tier - properties: - quantity_min: - type: integer - description: | - The minimum quantity of associated variant in the cart needed to qualify for this pricing of this tier. - example: 1 - quantity_max: - type: integer - description: | - The maximum allowed quantity of associated variant in the cart to qualify for the pricing of this tier. - example: 10 - type: - type: string - enum: - - fixed - - price - - percent - description: | - The type of adjustment that is made. Acceptable values: price – the adjustment amount per product; percent – the adjustment as a percentage of the original price; fixed – the adjusted absolute price of the product. - example: price - amount: - type: number - format: double - description: | - The price adjustment amount. This value along with the type will decide the price per variant for the pricing tier. - example: 3 - sku: - type: string - description: | - The SKU code associated with this `Price Record` if requested and it exists. - example: SMB-123 - title: Price Record - type: object - meta: - type: object - description: 'Data about the response, including pagination and collection totals.' - properties: - pagination: - type: object - description: 'Data about the response, including pagination and collection totals.' - title: Pagination - properties: - total: - type: integer - description: | - Total number of items in the result set. - example: 36 - count: - type: integer - description: | - Total number of items in the collection response. - example: 36 - per_page: - type: integer - description: | - The amount of items returned in the collection per page, controlled by the limit parameter. - example: 50 - current_page: - type: integer - description: | - The page you are currently on within the collection. - example: 1 - total_pages: - type: integer - description: | - The total number of pages in the collection. - example: 1 - links: - type: object - description: | - Pagination links for the previous and next parts of the whole collection. - properties: - previous: - type: string - description: | - Link to the previous page returned in the response. - current: - type: string - description: | - Link to the current page returned in the response. - example: '?page=1&limit=50' - next: - type: string - description: | - Link to the next page returned in the response. - title: Collection Meta - title: PriceRecord Collection Response - x-internal: false - PriceRecordResponse: - description: Response payload for the BigCommerce API. - type: object - properties: - data: - description: The Price Record object. - allOf: - - properties: - calculated_price: - type: number - format: double - description: | - The price of the variant as seen on the storefront if a price record is in effect. It will be equal to the `sale_price`, if set, and the `price` if there is not a `sale_price`. Read only. - example: 24.64 - date_created: - type: string - format: date-time - description: | - The date on which the Price entry was created. - example: '2022-08-23T19:59:23Z' - date_modified: - type: string - format: date-time - description: | - The date on which the Price entry was created. - example: '2022-08-23T19:59:23Z' - product_id: - type: integer - description: | - The id of the `Product` this `Price Record`'s variant_id is associated with. Read only. - example: 158 - - description: Price Record object used in batch create or update. - allOf: - - properties: - price_list_id: - type: integer - description: | - The Price List with which this price set is associated. - example: 2 - variant_id: - type: integer - description: | - The variant_id with which this price set is associated. Either variant_id or SKU is required. - example: 325 - sku: - type: string - description: | - The SKU with which this price set is associated. Either SKU or variant_id is required. - currency: - type: string - format: ISO-4217 - description: | - The 3-letter currency code with which this price set is associated. - example: usd - title: Price Record Identifiers - type: object - - type: object - description: Common Price Record properties. - title: PriceRecord Base - properties: - price: - type: number - format: double - description: | - The list price for the variant mapped in a Price List. Overrides any existing or Catalog list price for the variant/product. - x-required: - - put - example: 3.99 - sale_price: - type: number - format: double - description: | - The sale price for the variant mapped in a Price List. Overrides any existing or Catalog sale price for the variant/product. If empty, the sale price will be treated as not being set on this variant. - retail_price: - type: number - format: double - description: | - The retail price for the variant mapped in a Price List. Overrides any existing or Catalog retail price for the variant/product. If empty, the retail price will be treated as not being set on this variant. - map_price: - type: number - format: double - description: | - The MAP (Minimum Advertised Price) for the variant mapped in a Price List. Overrides any existing or Catalog MAP price for the variant/product. If empty, the MAP price will be treated as not being set on this variant. - bulk_pricing_tiers: - type: array - items: - type: object - title: Bulk Pricing Tier - properties: - quantity_min: - type: integer - description: | - The minimum quantity of associated variant in the cart needed to qualify for this tiers pricing. - example: 1 - quantity_max: - type: integer - description: | - The maximum allowed quantity of associated variant in the cart to qualify for this tiers pricing. - example: 10 - type: - type: string - enum: - - fixed - - price - - percent - description: | - The type of adjustment that is made. Acceptable values: price – the adjustment amount per product; percent – the adjustment as a percentage of the original price; fixed – the adjusted absolute price of the product. - example: price - amount: - type: number - format: double - description: | - The price adjustment amount. This value along with the type will decide the price per variant for the pricing tier. - example: 3 - sku: - type: string - description: | - The SKU code associated with this `Price Record` if requested and it exists. - example: SMB-123 - title: Price Record - type: object - meta: - $ref: '#/components/schemas/Meta' - title: Price Record Response - x-internal: false - PriceRecordBase: - type: object - description: Common Price Record properties. - title: PriceRecord Base - properties: - price: - type: number - format: double - description: | - The list price for the variant mapped in a Price List. Overrides any existing or Catalog list price for the variant/product. - x-required: - - put - example: 3.99 - sale_price: - type: number - format: double - description: | - The sale price for the variant mapped in a Price List. Overrides any existing or Catalog sale price for the variant/product. If empty, the sale price will be treated as not being set on this variant. - retail_price: - type: number - format: double - description: | - The retail price for the variant mapped in a Price List. Overrides any existing or Catalog retail price for the variant/product. If empty, the retail price will be treated as not being set on this variant. - map_price: - type: number - format: double - description: | - The MAP (Minimum Advertised Price) for the variant mapped in a Price List. Overrides any existing or Catalog MAP price for the variant/product. If empty, the MAP price will be treated as not being set on this variant. - bulk_pricing_tiers: - type: array - items: - type: object - title: Bulk Pricing Tier - properties: - quantity_min: - type: integer - description: | - The minimum quantity of associated variant in the cart needed to qualify for this tiers pricing. - example: 1 - quantity_max: - type: integer - description: | - The maximum allowed quantity of associated variant in the cart to qualify for this tiers pricing. - example: 10 - type: - type: string - enum: - - fixed - - price - - percent - description: | - The type of adjustment that is made. Acceptable values: price – the adjustment amount per product; percent – the adjustment as a percentage of the original price; fixed – the adjusted absolute price of the product. - example: price - amount: - type: number - format: double - description: | - The price adjustment amount. This value along with the type will decide the price per variant for the pricing tier. - example: 3 - sku: - type: string - description: | - The SKU code associated with this `Price Record` if requested and it exists. - example: SMB-123 - x-internal: false - PriceRecord: - description: The Price Record object. - allOf: - - properties: - calculated_price: - type: number - format: double - description: | - The price of the variant as seen on the storefront if a price record is in effect. It will be equal to the `sale_price`, if set, and the `price` if there is not a `sale_price`. Read only. - example: 24.64 - date_created: - type: string - format: date-time - description: | - The date on which the Price entry was created. - example: '2022-08-23T19:59:23Z' - date_modified: - type: string - format: date-time - description: | - The date on which the Price entry was created. - example: '2022-08-23T19:59:23Z' - product_id: - type: integer - description: | - The id of the `Product` this `Price Record`'s variant_id is associated with. Read only. - example: 158 - - description: Price Record object used in batch create or update. - allOf: - - properties: - price_list_id: - type: integer - description: | - The Price List with which this price set is associated. - example: 2 - variant_id: - type: integer - description: | - The variant ID with which this price set is associated. Either variant_id or SKU is required. - example: 325 - sku: - type: string - description: | - The SKU with which this price set is associated. Either SKU or variant_id is required. - currency: - type: string - format: ISO-4217 - description: | - The 3-letter currency code with which this price set is associated. - example: usd - title: Price Record Identifiers - type: object - - type: object - description: Common Price Record properties. - title: PriceRecord Base - properties: - price: - type: number - format: double - description: | - The list price for the variant mapped in a Price List. Overrides any existing or Catalog list price for the variant/product. - x-required: - - put - example: 3.99 - sale_price: - type: number - format: double - description: | - The sale price for the variant mapped in a Price List. Overrides any existing or Catalog sale price for the variant/product. If empty, the sale price will be treated as not being set on this variant. - retail_price: - type: number - format: double - description: | - The retail price for the variant mapped in a Price List. Overrides any existing or Catalog retail price for the variant/product. If empty, the retail price will be treated as not being set on this variant. - map_price: - type: number - format: double - description: | - The MAP (Minimum Advertised Price) for the variant mapped in a Price List. Overrides any existing or Catalog MAP price for the variant/product. If empty, the MAP price will be treated as not being set on this variant. - bulk_pricing_tiers: - type: array - items: - type: object - title: Bulk Pricing Tier - properties: - quantity_min: - type: integer - description: | - The minimum quantity of associated variant in the cart needed to qualify for this tiers pricing. - example: 1 - quantity_max: - type: integer - description: | - The maximum allowed quantity of associated variant in the cart to qualify for this tiers pricing. - example: 10 - type: - type: string - enum: - - fixed - - price - - percent - description: | - The type of adjustment that is made. Acceptable values: price – the adjustment amount per product; percent – the adjustment as a percentage of the original price; fixed – the adjusted absolute price of the product. - example: price - amount: - type: number - format: double - description: | - The price adjustment amount. This value along with the type will decide the price per variant for the pricing tier. - example: 3 - sku: - type: string - description: | - The SKU code associated with this `Price Record` if requested and it exists. - example: SMB-123 - title: Price Record - type: object - x-internal: false - BulkPricingTier: - type: object - title: Bulk Pricing Tier - properties: - quantity_min: - type: integer - description: | - The minimum quantity of associated variant in the cart needed to qualify for this pricing tier. - example: 1 - quantity_max: - type: integer - description: | - The maximum allowed quantity of associated variant in the cart to qualify for this pricing tier. - example: 10 - type: - type: string - enum: - - fixed - - price - - percent - description: | - The type of adjustment that is made. Acceptable values: price – the adjustment amount per product; percent – the adjustment as a percentage of the original price; fixed – the adjusted absolute price of the product. - example: price - amount: - type: number - format: double - description: | - The price adjustment amount. This value together with the adjustment type determines the price per variant for the pricing tier. - example: 3 - x-internal: false - PriceRecordPut: - type: object - allOf: - - type: object - description: Common Price Record properties. - title: PriceRecord Base - properties: - price: - type: number - format: double - description: | - The list price for the variant mapped in a Price List. Overrides any existing or Catalog list price for the variant/product. - x-required: - - put - example: 3.99 - sale_price: - type: number - format: double - description: | - The sale price for the variant mapped in a Price List. Overrides any existing or Catalog sale price for the variant/product. If empty, the sale price will be treated as not being set on this variant. - retail_price: - type: number - format: double - description: | - The retail price for the variant mapped in a Price List. Overrides any existing or Catalog retail price for the variant/product. If empty, the retail price will be treated as not being set on this variant. - map_price: - type: number - format: double - description: | - The MAP (Minimum Advertised Price) for the variant mapped in a Price List. Overrides any existing or Catalog MAP price for the variant/product. If empty, the MAP price will be treated as not being set on this variant. - bulk_pricing_tiers: - type: array - items: - type: object - title: Bulk Pricing Tier - properties: - quantity_min: - type: integer - description: | - The minimum quantity of associated variant in the cart needed to qualify for the pricing of this tier. - example: 1 - quantity_max: - type: integer - description: | - The maximum allowed quantity of associated variant in the cart to qualify for the pricing of this tier. - example: 10 - type: - type: string - enum: - - fixed - - price - - percent - description: | - The type of adjustment that is made. Acceptable values: price – the adjustment amount per product; percent – the adjustment as a percentage of the original price; fixed – the adjusted absolute price of the product. - example: price - amount: - type: number - format: double - description: | - The price adjustment amount. This value along with the type will decide the price per variant for the pricing tier. - example: 3 - sku: - type: string - description: | - The SKU code associated with this `Price Record` if requested and it exists. - example: SMB-123 - title: Price Record Put - x-internal: false - PriceRecordCollectionPut: - type: array - items: - description: Price Record object used in a batch create or update request. - allOf: - - properties: - variant_id: - type: integer - description: | - The variant ID with which this price set is associated. Either variant_id or SKU is required. - example: 331 - sku: - type: string - description: | - The SKU for the variant with which this price set is associated. Either SKU or variant_id is required. - example: SMB-123 - currency: - type: string - format: ISO-4217 - description: | - The 3-letter currency code with which this price set is associated. - example: usd - - type: object - description: Common Price Record properties. - title: PriceRecord Base - properties: - price: - type: number - format: double - description: | - The list price for the variant mapped in a Price List. Overrides any existing or Catalog list price for the variant/product. - x-required: - - put - example: 3.99 - sale_price: - type: number - format: double - description: | - The sale price for the variant mapped in a Price List. Overrides any existing or Catalog sale price for the variant/product. If empty, the sale price will be treated as not being set on this variant. - retail_price: - type: number - format: double - description: | - The retail price for the variant mapped in a Price List. Overrides any existing or Catalog retail price for the variant/product. If empty, the retail price will be treated as not being set on this variant. - map_price: - type: number - format: double - description: | - The MAP (Minimum Advertised Price) for the variant mapped in a Price List. Overrides any existing or Catalog MAP price for the variant/product. If empty, the MAP price will be treated as not being set on this variant. - bulk_pricing_tiers: - type: array - items: - type: object - title: Bulk Pricing Tier - properties: - quantity_min: - type: integer - description: | - The minimum quantity of associated variant in the cart needed to qualify for this pricing tier. - example: 1 - quantity_max: - type: integer - description: | - The maximum allowed quantity of associated variant in the cart to qualify for this pricing tier. - example: 10 - type: - type: string - enum: - - fixed - - price - - percent - description: | - The type of adjustment that is made. Acceptable values: price – the adjustment amount per product; percent – the adjustment as a percentage of the original price; fixed – the adjusted absolute price of the product. - example: price - amount: - type: number - format: double - description: | - The price adjustment amount. This value together with the adjustment type will determine the price per variant for the pricing tier. - example: 3 - sku: - type: string - description: | - The SKU code associated with this `Price Record` if requested and it exists. - example: SMB-123 - title: PriceRecord Batch Item - type: object - title: Price Record Collection Put - x-internal: false - PriceRecordBatchItem: - description: Price Record object used in batch create or update request. - allOf: - - properties: - variant_id: - type: integer - description: | - The variant ID with which this price set is associated. Either variant_id or SKU is required. - example: 331 - sku: - type: string - description: | - The SKU for the variant with which this price set is associated. Either SKU or variant_id is required. - example: SMB-123 - currency: - type: string - format: ISO-4217 - description: | - The 3-letter currency code with which this price set is associated. - example: usd - - type: object - description: Common Price Record properties. - title: PriceRecord Base - properties: - price: - type: number - format: double - description: | - The list price for the variant mapped in a Price List. Overrides any existing or Catalog list price for the variant/product. - x-required: - - put - example: 3.99 - sale_price: - type: number - format: double - description: | - The sale price for the variant mapped in a Price List. Overrides any existing or Catalog sale price for the variant/product. If empty, the sale price will be treated as not being set on this variant. - retail_price: - type: number - format: double - description: | - The retail price for the variant mapped in a Price List. Overrides any existing or Catalog retail price for the variant/product. If empty, the retail price will be treated as not being set on this variant. - map_price: - type: number - format: double - description: | - The MAP (Minimum Advertised Price) for the variant mapped in a Price List. Overrides any existing or Catalog MAP price for the variant/product. If empty, the MAP price will be treated as not being set on this variant. - bulk_pricing_tiers: - type: array - items: - type: object - title: Bulk Pricing Tier - properties: - quantity_min: - type: integer - description: | - The minimum quantity of associated variant in the cart needed to qualify for this pricing tier. - example: 1 - quantity_max: - type: integer - description: | - The maximum allowed quantity of associated variant in the cart to qualify for this pricing tier. - example: 10 - type: - type: string - enum: - - fixed - - price - - percent - description: | - The type of adjustment that is made. Acceptable values: price – the adjustment amount per product; percent – the adjustment as a percentage of the original price; fixed – the adjusted absolute price of the product. - example: price - amount: - type: number - format: double - description: | - The price adjustment amount. This value together with the adjustment type will determine the price per variant for the pricing tier. - example: 3 - sku: - type: string - description: | - The SKU code associated with this `Price Record` if requested and it exists. - example: SMB-123 - title: PriceRecord Batch Item - type: object - x-internal: false - PriceRecordIdentifiers: - description: Price Record object used in batch create or update request. - allOf: - - properties: - price_list_id: - type: integer - description: | - The Price List with which this price set is associated. - example: 2 - variant_id: - type: integer - description: | - The variant ID with which this price set is associated. Either variant_id or SKU is required. - example: 325 - sku: - type: string - description: | - The SKU with which this price set is associated. Either SKU or variant_id is required. - currency: - type: string - format: ISO-4217 - description: | - The 3-letter currency code with which this price set is associated. - example: usd - title: Price Record Identifiers - type: object - x-internal: false - SuccessBatchResponse: - type: object - description: Empty object. - title: Success Batch Response - x-internal: false - PriceRecordBatchErrorResponse: - description: Errors during batch usage for the BigCommerce API. - type: object - properties: - batch_errors: - type: array - items: - description: Error during Price Record batch PUT request. Includes data sent in the request and errors. - type: object - properties: - data: - description: Price Record object used in a batch create or update request. - allOf: - - properties: - price_list_id: - type: integer - description: | - The Price List with which this price set is associated. - example: 2 - variant_id: - type: integer - description: | - The variant ID with which this price set is associated. Either variant_id or SKU is required. - example: 325 - sku: - type: string - description: | - The SKU with which this price set is associated. Either SKU or variant_id is required. - currency: - type: string - format: ISO-4217 - description: | - The 3-letter currency code with which this price set is associated. - example: usd - title: Price Record Identifiers - type: object - field_errors: - type: object - properties: {} - additionalProperties: true - title: Detailed Errors - title: PriceRecord Batch Error Set - title: PriceRecord Batch Error Response - x-internal: false - PriceRecordBatchErrorSet: - description: Error during Price Record batch PUT request. Includes data sent in the request and errors. - type: object - properties: - data: - description: Price Record object used in batch create or update request. - allOf: - - properties: - price_list_id: - type: integer - description: | - The Price List with which this price set is associated. - example: 2 - variant_id: - type: integer - description: | - The variant ID with which this price set is associated. Either variant_id or SKU is required. - example: 325 - sku: - type: string - description: | - The SKU with which this price set is associated. Either SKU or variant_id is required. - currency: - type: string - format: ISO-4217 - description: | - The 3-letter currency code with which this price set is associated. - example: usd - title: Price Record Identifiers - type: object - field_errors: - type: object - properties: {} - additionalProperties: true - title: Detailed Errors - title: PriceRecord Batch Error Set - x-internal: false CollectionMeta: type: object description: 'Data related the response, including pagination and collection totals.' @@ -4091,55 +2990,6 @@ components: Link to the next page returned in the response. title: Collection Meta x-internal: false - Pagination: - type: object - description: 'Data related to the response, including pagination and collection totals.' - title: Pagination - properties: - total: - type: integer - description: | - Total number of items in the result set. - example: 36 - count: - type: integer - description: | - Total number of items in the collection response. - example: 36 - per_page: - type: integer - description: | - The amount of items returned in the collection per page, controlled by the limit parameter. - example: 50 - current_page: - type: integer - description: | - The page you are currently on within the collection. - example: 1 - total_pages: - type: integer - description: | - The total number of pages in the collection. - example: 1 - links: - type: object - description: | - Pagination links for the previous and next parts of the whole collection. - properties: - previous: - type: string - description: | - Link to the previous page returned in the response. - current: - type: string - description: | - Link to the current page returned in the response. - example: '?page=1&limit=50' - next: - type: string - description: | - Link to the next page returned in the response. - x-internal: false Meta: title: Response meta type: object @@ -4174,42 +3024,6 @@ components: title: Detailed Errors title: Error Response x-internal: false - BaseError: - type: object - description: | - Error payload for the BigCommerce API. - properties: - status: - description: | - The HTTP status code. - type: integer - title: - description: | - The error title describing the particular error. - type: string - type: - type: string - instance: - type: string - title: Base Error - x-internal: false - NotFound: - description: Error payload for the BigCommerce API. - type: object - properties: - status: - description: | - 404 HTTP status code. - type: integer - title: - description: The error title describing the particular error. - type: string - type: - type: string - instance: - type: string - title: Not Found - x-internal: false CreateBatchPriceListAssignmentsRequest: type: array description: Batch of price list assignments. @@ -4231,15 +3045,14 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header - diff --git a/reference/pricing.sf.yml b/reference/pricing.sf.yml index 1f097dd9f..4b20d2f21 100644 --- a/reference/pricing.sf.yml +++ b/reference/pricing.sf.yml @@ -45,39 +45,45 @@ paths: properties: channel_id: type: integer - description: The channel context that pricing should be evaluated within. The default BC storefront is channel 1 + description: The channel ID that pricing evaluates within. The default BigCommerce storefront is channel 1. example: 1 currency_code: type: string - description: The currency of prices to be returned for this request + description: The currency code of prices this request returns. + example: USD customer_group_id: type: integer - description: 'The customer group relevant for any customer group pricing, tax values, etc.' + description: The customer group ID that's relevant for any customer group pricing, tax values, etc. items: type: array - description: The items to fetch prices for + description: The items for which to fetch prices. + items: type: object properties: product_id: type: integer - description: The (required) product ID of the item + description: The (required) product ID of the item. variant_id: type: number - description: The (optional) variant ID of the item + description: The (optional) variant ID of the item. options: type: array - description: The (optional) option configuration of the product. May be "partially" configured for estimates. + description: The option configuration of the product (optional); might be partially configured for estimates. items: type: object properties: option_id: type: integer - description: The ID of the variant option or modifier option being configured for this product + description: The ID of the variant option or modifier option that is being configured for this product. value_id: type: integer - description: 'The ID of the value matching the option being configured. Note: must be ID, not the value.' + description: |- + The ID of the value matching the option that's being configured. + + **Note:*** This must be the ID, not the value. + description: Details/configuration for the product to request a price for. required: true responses: @@ -87,6 +93,7 @@ paths: application/json: schema: type: object + description: Note that a storeʼs [tax settings](/docs/rest-management/tax-settings) may affect the calculations for `tax_inclusive` and `tax_exclusive` prices. properties: data: type: array @@ -95,19 +102,20 @@ paths: properties: product_id: type: integer - description: The product ID this price was generated for + description: The (required) product ID of the item. variant_id: type: integer - description: The (optional) variant ID this price was generated for + description: The (optional) variant ID of the item. options: type: array - description: The optional product option configuration this price was generated for + description: The optional product option configuration for which this price was generated. + items: type: object properties: option_id: type: integer - description: The ID of the variant option or modifier option configured for this price + description: The ID of the variant option or modifier option configured for this price. value_id: type: integer description: The selected value ID for the configured option. @@ -116,81 +124,81 @@ paths: properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group + description: The estimated tax inclusive price for this product based on the provided customer group. description: The (optional) RRP/retail price configured for this product. Used for price comparison and storefront display purposes. sale_price: type: object properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group + description: The estimated tax inclusive price for this product based on the provided customer group. description: The merchant-entered sale price for a product overwrites the default price. The sale_price is optional. minimum_advertised_price: type: object properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group + description: The estimated tax inclusive price for this product based on the provided customer group. description: The minimum advertised price (MAP) allowed to be shown on a storefront. A value supplied by the merchant and used for display purposes. price: type: object properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group + description: The estimated tax inclusive price for this product based on the provided customer group. description: The merchant-entered price for a product could be including or excluding tax. Price must be defined when creating a product and serves as the default price. calculated_price: type: object properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: 'The shopper price for a product including modifier, option, and option set rules. Calculated_price may include or exclude estimates for tax.' + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The shopper price for a product including modifier, option, and option set rules. The `calculated_price` may include or exclude estimates for tax. price_range: type: object properties: @@ -199,33 +207,33 @@ paths: properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The price for a product including estimates for tax + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The price for a product including estimates for tax. maximum: type: object properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The price for a product including estimates for tax + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The price for a product including estimates for tax. description: The minimum and maximum price that will typically apply to this product. Only used for complex products (products with variants). retail_price_range: type: object @@ -235,34 +243,34 @@ paths: properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The price for a product including estimates for tax + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The price for a product including estimates for tax. maximum: type: object properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The price for a product including estimates for tax - description: The product's variants that will typically apply to this product. + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The price for a product including estimates for tax. + description: The productʼs variants that will typically apply to this product. bulk_pricing: type: array items: @@ -331,6 +339,11 @@ paths: maximum: 1 discount_amount: 1 discount_type: percent + tax_discount_amount: + - as_entered: 10 + tax_inclusive: 10 + tax_exclusive: 10 + entered_inclusive: false meta: {} components: schemas: @@ -339,10 +352,10 @@ components: properties: minimum: type: integer - description: The minumum quantity required to trigger this bulk pricing discount + description: The minimum quantity required to trigger this bulk pricing discount. maximum: type: integer - description: The maximum quantity (or 0 for unlimited) to trigger this bulk pricing discount + description: The maximum quantity (or 0 for unlimited) to trigger this bulk pricing discount. discount_amount: type: number discount_type: @@ -351,6 +364,24 @@ components: - price - percent - fixed + tax_discount_amount: + type: array + description: Formats the `bulk_pricing.discount_amount` into the tax price amounts. + items: + type: object + properties: + as_entered: + type: number + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. + tax_inclusive: + type: number + description: The estimated tax inclusive price for this product based on the provided customer group. + tax_exclusive: + type: number + description: The estimated tax exclusive price for this product based on the provided customer group. + entered_inclusive: + type: boolean + description: Determines whether the 'as_entered' price is inclusive or exclusive of tax based on the store's tax jurisdiction. x-internal: false PricingResponse: type: object @@ -362,10 +393,10 @@ components: properties: product_id: type: integer - description: The product ID this price was generated for + description: The (required) product ID of the item. variant_id: type: integer - description: The (optional) variant ID this price was generated for + description: The (optional) variant ID of the item. options: type: array description: The optional product option configuration this price was generated for @@ -383,81 +414,81 @@ components: properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The (optional) RRP/retail price configured for this product + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The (optional) RRP/retail price configured for this product. sale_price: type: object properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The price for a product including estimates for tax + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The price for a product including estimates for tax. minimum_advertised_price: type: object properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The price for a product including estimates for tax + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The price for a product including estimates for tax. price: type: object properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The price for a product including estimates for tax + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The price for a product including estimates for tax. calculated_price: type: object properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The price for a product including estimates for tax + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The price for a product including estimates for tax. price_range: type: object properties: @@ -466,34 +497,34 @@ components: properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The price for a product including estimates for tax + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The price for a product including estimates for tax. maximum: type: object properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The price for a product including estimates for tax - description: 'For estimated prices, the minimum/maximum price that will typically apply to this product' + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The price for a product including estimates for tax. + description: For estimated prices, the minimum/maximum price that will typically apply to this product. retail_price_range: type: object properties: @@ -502,34 +533,34 @@ components: properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The price for a product including estimates for tax + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The price for a product including estimates for tax. maximum: type: object properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group + description: The estimated tax inclusive price for this product based on the provided customer group. description: The price for a product including estimates for tax - description: 'For estimated prices, the minimum/maximum price that will typically apply to this product' + description: For estimated prices, the minimum/maximum price that will typically apply to this product. bulk_pricing: type: array items: @@ -537,18 +568,38 @@ components: properties: minimum: type: integer - description: The minumum quantity required to trigger this bulk pricing discount + description: The minimum quantity required to trigger this bulk pricing discount. maximum: type: integer - description: The maximum quantity (or 0 for unlimited) to trigger this bulk pricing discount + description: The maximum quantity (or 0 for unlimited) to trigger this bulk pricing discount. discount_amount: type: number + description: The price reduction set by the merchant for this bulk pricing discount. discount_type: type: string enum: - price - percent - fixed + description: The format of the price reduction set by the merchant for this bulk pricing discount. + tax_discount_amount: + type: array + description: Formats the `bulk_pricing.discount_amount` into the tax price amounts. + items: + type: object + properties: + as_entered: + type: number + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. + tax_inclusive: + type: number + description: The estimated tax inclusive price for this product based on the provided customer group. + tax_exclusive: + type: number + description: The estimated tax exclusive price for this product based on the provided customer group. + entered_inclusive: + type: boolean + description: Determines whether the 'as_entered' price is inclusive or exclusive of tax based on the store's tax jurisdiction. meta: type: object properties: {} @@ -563,70 +614,71 @@ components: properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The price for a product including estimates for tax + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The price for a product including estimates for tax. maximum: type: object properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The price for a product including estimates for tax - description: 'For estimated prices, the minimum/maximum price that will typically apply to this product' + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The price for a product including estimates for tax. + description: For estimated prices, the minimum/maximum price that will typically apply to this product. x-internal: false TaxPrice: type: object properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The price for a product including estimates for tax + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The price for a product including estimates for tax. x-internal: false ItemPricing: type: object properties: product_id: type: integer - description: The product ID this price was generated for + description: The (required) product ID of the item. variant_id: type: integer - description: The (optional) variant ID this price was generated for + description: The (optional) variant ID of the item. options: type: array - description: The optional product option configuration this price was generated for + description: The optional product option configuration for which this price was generated. + items: type: object properties: option_id: type: integer - description: The ID of the variant option or modifier option configured for this price + description: The ID of the variant option or modifier option configured for this price. value_id: type: integer description: The selected value ID for the configured option. @@ -635,81 +687,81 @@ components: properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The (optional) RRP/retail price configured for this product + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The (optional) RRP/retail price configured for this product. sale_price: type: object properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The price for a product including estimates for tax + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The price for a product including estimates for tax. minimum_advertised_price: type: object properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The price for a product including estimates for tax + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The price for a product including estimates for tax. price: type: object properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The price for a product including estimates for tax + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The price for a product including estimates for tax. calculated_price: type: object properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The price for a product including estimates for tax + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The price for a product including estimates for tax. price_range: type: object properties: @@ -718,34 +770,34 @@ components: properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The price for a product including estimates for tax + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The price for a product including estimates for tax. maximum: type: object properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Determines whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax. jurisdiction tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The price for a product including estimates for tax - description: 'For estimated prices, the minimum/maximum price that will typically apply to this product' + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The price for a product including estimates for tax. + description: For estimated prices, the minimum/maximum price that will typically apply to this product. retail_price_range: type: object properties: @@ -754,34 +806,34 @@ components: properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The price for a product including estimates for tax + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The price for a product including estimates for tax. maximum: type: object properties: as_entered: type: number - description: The price provided by the merchant as entered in their catalog/price list (may be inc or ex) + description: The price provided by the merchant as entered in their catalog/price list; may include or exclude tax. entered_inclusive: type: boolean - description: 'Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction' + description: Whether the `as_entered` price is inclusive or exclusive of tax, based on the stores tax jurisdiction. tax_exclusive: type: number - description: The estimated tax exclusive price for this product based on the provided customer group + description: The estimated tax exclusive price for this product based on the provided customer group. tax_inclusive: type: number - description: The estimated tax inclusive price for this product based on the provided customer group - description: The price for a product including estimates for tax - description: 'For estimated prices, the minimum/maximum price that will typically apply to this product' + description: The estimated tax inclusive price for this product based on the provided customer group. + description: The price for a product including estimates for tax. + description: For estimated prices, the minimum/maximum price that will typically apply to this product. bulk_pricing: type: array items: @@ -792,10 +844,10 @@ components: properties: product_id: type: integer - description: The (required) product ID of the item + description: The (required) product ID of the item. variant_id: type: number - description: The (optional) variant ID of the item + description: The (optional) variant ID of the item. options: type: array description: The (optional) option configuration of the product. May be "partially" configured for estimates. @@ -804,10 +856,14 @@ components: properties: option_id: type: integer - description: The ID of the variant option or modifier option being configured for this product + description: The ID of the variant option or modifier option being configured for this product. value_id: type: integer - description: 'The ID of the value matching the option being configured. Note: must be ID, not the value.' + description: |- + The ID of the value matching the option being configured. + + **Note:** must be ID, not the value. + description: Details/configuration for the product to request a price for. x-internal: false PricingRequest: @@ -815,27 +871,28 @@ components: properties: channel_id: type: integer - description: The channel context that pricing should be evaluated within. The default BC storefront is channel 1 + description: The channel ID that pricing evaluates within. The default BigCommerce storefront is channel 1. example: 1 currency_code: type: string - description: The currency of prices to be returned for this request + description: The currency of prices to be returned for this request. example: USD customer_group_id: type: integer - description: 'The customer group relevant for any customer group pricing, tax values, etc.' + description: The customer group relevant for any customer group pricing, tax values, etc. items: type: array - description: The items to fetch prices for + description: The items for which to fetch prices. + items: type: object properties: product_id: type: integer - description: The (required) product ID of the item + description: The (required) product ID of the item. variant_id: type: number - description: The (optional) variant ID of the item + description: The (optional) variant ID of the item. options: type: array description: The (optional) option configuration of the product. May be "partially" configured for estimates. @@ -844,10 +901,14 @@ components: properties: option_id: type: integer - description: The ID of the variant option or modifier option being configured for this product + description: The ID of the variant option or modifier option being configured for this product. value_id: type: integer - description: 'The ID of the value matching the option being configured. Note: must be ID, not the value.' + description: |- + The ID of the value matching the option being configured. + + **Note:** This must be the ID, not the value. + description: Details/configuration for the product to request a price for. x-internal: false securitySchemes: @@ -864,14 +925,14 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header diff --git a/reference/redirects.v3.yml b/reference/redirects.v3.yml index 7d68dca53..f5ae6e6a8 100644 --- a/reference/redirects.v3.yml +++ b/reference/redirects.v3.yml @@ -20,6 +20,7 @@ security: - X-Auth-Token: [] tags: - name: Redirects + - name: Import-Export paths: '/storefront/redirects': parameters: @@ -28,7 +29,7 @@ paths: tags: - Redirects summary: Get Redirects - description: Returns a collection of the store's 301 redirects across all sites. + description: Returns a collection of the storeʼs 301 redirects across all sites. operationId: GetRedirects parameters: - name: site_id @@ -65,6 +66,7 @@ paths: - from_path - type - site_id + - id - name: direction in: query description: 'Sort direction. Acceptable values are `asc`, `desc`.' @@ -155,6 +157,231 @@ paths: '204': description: No Content content: {} + '/storefront/redirects/imex/jobs': + parameters: + - $ref: '#/components/parameters/Accept' + get: + tags: + - Import-Export + summary: Get Redirect Import-Export Jobs + description: Returns a collection of the storeʼs 301 redirects across all sites. + operationId: getRedirectImportExportJobs + parameters: + - name: id + in: query + description: Filters results by Redirect Import-Export job ID. + style: form + explode: false + schema: + type: string + - name: type + in: query + description: Filters results by the type of the Redirect Import-Export job. + style: form + explode: false + schema: + $ref: '#/components/schemas/ImportExportJobType' + - name: status + in: query + description: Filters results by the status of the Redirect Import-Export job. + style: form + explode: false + schema: + $ref: '#/components/schemas/ImportExportJobStatus' + - name: limit + in: query + description: Determines the number of items returned per page. The default is 10 items per page. + schema: + type: integer + default: 10 + - name: page + in: query + description: Specifies the page number to return when the number of items returned exceeds the page limit. Used to paginate large collections. + schema: + type: integer + responses: + '200': + description: '' + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/301RedirectImportExportJobRead' + meta: + $ref: '#/components/schemas/MetaPaginationObject' + '/storefront/redirects/imex/export': + parameters: + - $ref: '#/components/parameters/Accept' + post: + tags: + - Import-Export + summary: Create Redirects Export Job + description: Creates a new 301 Redirects export job. + operationId: createRedirectExportJob + parameters: + - $ref: '#/components/parameters/ContentType' + requestBody: + content: + application/json: + schema: + type: object + properties: + site_id: + type: integer + nullable: true + default: null + description: The site ID for which you wish to export redirects. If no site ID is provided, the request exports all redirects for all sites. + redirect_ids: + type: array + items: + type: integer + default: [] + description: A list of the redirect IDs you wish to export. If no redirect IDs are provided, the request exports all redirects for the given site selection. + include_dynamic_target_urls: + type: boolean + default: false + description: If true, the exported CSV will contain an additional read-only column containing the target URL for dynamic redirects. + description: Data necessary to create a new 301 Redirects export job. + required: true + responses: + '201': + description: Created + content: + application/json: + schema: + type: object + properties: + id: + type: string + example: ab1c2de3-f4gh-5678-i90j-klm12n345o67 + '429': + description: Your store already has an active Redirects import or export job running. + '409': + description: No Redirects in your store meet the criteria in your request. + '/storefront/redirects/imex/import': + parameters: + - $ref: '#/components/parameters/Accept' + post: + tags: + - Import-Export + summary: Create Redirects Import Job + description: Creates a new 301 Redirects import job. + operationId: createRedirectImportJob + parameters: + - $ref: '#/components/parameters/ContentTypeFormData' + requestBody: + content: + multipart/form-data: + schema: + type: object + properties: + import_file: + description: |- + A CSV file containing a list of Redirects to be imported. + + The headers must be defined as follows: + + `Domain,Old Path,Manual URL/Path,Dynamic Target Type,Dynamic Target ID` + + Not every line will have a value for every column. + type: string + format: binary + example: |- + Domain,Old Path,Manual URL/Path,Dynamic Target Type,Dynamic Target ID + store.example.com,/old-path,/new-manual-path,, + store.example.com,/old-product,,Product,12 + store.example.com,/old-brand,,Brand,34 + store.example.com,/old-category,,Category,56 + store.example.com,/old-page,,Page,78 + store.example.com,/old-post,,Post,90 + required: + - import_file + description: Data necessary to create a new 301 Redirects import job. + required: true + responses: + '201': + description: Created + content: + application/json: + schema: + type: object + properties: + id: + type: string + example: ab1c2de3-f4gh-5678-i90j-klm12n345o67 + '400': + description: The provided form data was invalid or the file is not a CSV. + '413': + description: The provided file is too large. The maximum file size is 20MB. + '429': + description: Your store already has an active Redirects import or export job running. + '/storefront/redirects/imex/export/{uuid}/events': + parameters: + - $ref: '#/components/parameters/AcceptEventStream' + - $ref: '#/components/parameters/ImportExportIdParam' + get: + tags: + - Import-Export + summary: Open Redirect Export Event Stream + description: Opens an event stream to receive live updates from an export job. + operationId: getRedirectExportEvents + responses: + '200': + description: Stream of export events. The `data` attribute is stringified JSON. + content: + text/event-stream: + schema: + type: string + example: 'event: message\ndata: {"job_id":"cfccdd6e-956e-4484-8cc2-a610db26bad9","status":"complete","completed_items":100,"total_items":100}\n\n' + '404': + description: The provided export job ID does not exist. + '/storefront/redirects/imex/import/{uuid}/events': + parameters: + - $ref: '#/components/parameters/AcceptEventStream' + - $ref: '#/components/parameters/ImportExportIdParam' + get: + tags: + - Import-Export + summary: Open Redirect Import Event Stream + description: Opens an event stream to receive live updates from an import job. + operationId: getRedirectImportEvents + responses: + '200': + description: Stream of import events. The `data` attribute is stringified JSON. + content: + text/event-stream: + schema: + type: string + example: 'event: message\ndata: {{"job_id":"a4abaf59-9c25-4f37-a09d-66e6054229a1","status":"complete","completed_items":100,"failed_items":100,"total_items":93,"errors":[]}\n\n' + '404': + description: The provided import job ID does not exist. + '/storefront/redirects/imex/export/{uuid}/download': + parameters: + - $ref: '#/components/parameters/ContentTypeCsv' + - $ref: '#/components/parameters/ImportExportIdParam' + get: + tags: + - Import-Export + summary: Download Redirect Export + description: Downloads the CSV file containing the results of an export job. + operationId: getRedirectExportDownload + responses: + '200': + description: The exported Redirects in CSV format + content: + text/csv: + schema: + type: string + format: binary + example: | + Domain,Old Path,Manual URL/Path,Dynamic Target Type,Dynamic Target ID + store.example.com,/old-path,/redirect-target,, + '404': + description: The requested export download does not exist. components: parameters: Accept: @@ -165,6 +392,14 @@ components: schema: type: string default: 'application/json' + AcceptEventStream: + name: Accept + in: header + required: true + description: 'The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body.' + schema: + type: string + default: 'text/event-stream' ContentType: name: Content-Type in: header @@ -173,6 +408,30 @@ components: schema: type: string default: 'application/json' + ContentTypeFormData: + name: Content-Type + in: header + required: true + description: 'The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the request body.' + schema: + type: string + default: 'multipart/form-data' + ContentTypeCsv: + name: Content-Type + in: header + required: true + description: 'The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the request body.' + schema: + type: string + default: 'text/csv' + ImportExportIdParam: + name: uuid + description: The import-export job identifier. + in: path + required: true + schema: + type: string + format: uuid schemas: Error: type: object @@ -181,31 +440,26 @@ components: type: integer message: type: string - x-internal: false ErrorResponse400: type: object properties: schema: $ref: '#/components/schemas/Error' - x-internal: false ErrorResponse404: type: object properties: schema: $ref: '#/components/schemas/Error' - x-internal: false ErrorResponse409: type: object properties: schema: $ref: '#/components/schemas/Error' - x-internal: false ErrorResponse422: type: object properties: schema: $ref: '#/components/schemas/Error' - x-internal: false 301RedirectUpsert: required: - from_path @@ -219,12 +473,10 @@ components: type: integer to: $ref: '#/components/schemas/RedirectTo' - description: 'Data necessary to create or update a redirect. If there’s a conflict on the from_path and site_id, the redirect will be overwritten with new data.' - x-internal: false + description: Data necessary to create or update a redirect. If there’s a conflict on the from_path and site_id, the redirect will be overwritten with new data. 301RedirectRead: type: object - description: 'Full detail of a Redirect, optionally including the full destination URL.' - x-internal: false + description: Full detail of a Redirect, optionally including the full destination URL. properties: id: type: integer @@ -240,6 +492,63 @@ components: description: Full destination URL for the redirect. Must be explicitly included via URL parameter. format: uri example: 'https://store-domain.com/new-url' + ImportExportJobType: + type: string + enum: + - import + - export + ImportExportJobStatus: + type: string + enum: + - new + - working + - complete + - aborted + - failed + ImportErrors: + type: array + items: + type: object + description: Detail of an error that occurred during an import job. + properties: + row: + type: integer + description: The row in the import CSV where the error occurred. + message: + type: string + 301RedirectImportExportJobRead: + type: object + description: Full detail of a Redirect Import-Export job. + properties: + id: + type: string + format: uuid + description: The Import-Export job ID. + type: + $ref: '#/components/schemas/ImportExportJobType' + status: + $ref: '#/components/schemas/ImportExportJobStatus' + completed_items: + type: integer + description: The number of items that were successfully imported or exported. + failed_items: + type: integer + description: The number of items that were not successfully imported or exported. + total_items: + type: integer + description: The number of items in the import or export job. + errors: + $ref: '#/components/schemas/ImportErrors' + created_at: + type: string + format: date-time + description: 'The date-time that the import-export job was created, formatted as an [RFC-3339](https://www.ietf.org/rfc/rfc3339.txt) string.' + example: '2022-01-04T04:15:50.000Z' + completed_at: + type: string + format: date-time + description: 'The date-time that the import-export job was completed, formatted as an [RFC-3339](https://www.ietf.org/rfc/rfc3339.txt) string.' + example: '2022-01-04T04:15:50.000Z' MetaPaginationObject: type: object properties: @@ -275,7 +584,6 @@ components: current: type: string example: '?limit=5&page=1' - x-internal: false RedirectTo: title: RedirectTo type: object @@ -295,13 +603,11 @@ components: maxLength: 2048 type: string example: /new-url/ - x-internal: false DetailedErrors: type: object properties: {} additionalProperties: true title: Detailed Errors - x-internal: false BaseError: type: object properties: @@ -319,7 +625,6 @@ components: type: string description: | Error payload for the BigCommerce API. - x-internal: false ErrorResponse: allOf: - $ref: '#/components/schemas/BaseError' @@ -327,7 +632,6 @@ components: properties: errors: $ref: '#/components/schemas/DetailedErrors' - x-internal: false securitySchemes: X-Auth-Token: name: X-Auth-Token @@ -336,22 +640,22 @@ components: | UI Name | Permission | Parameter | |:--------|:-----------|:----------| - | Content | modify | `store_v2_content` | - | Content | read-only | `store_v2_content_read_only` | + | Content | modify | `store_v2_content` | + | Content | read-only | `store_v2_content_read_only` | ### Authentication header | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header diff --git a/reference/scripts.v3.yml b/reference/scripts.v3.yml index cb9b591b5..2c1795db6 100644 --- a/reference/scripts.v3.yml +++ b/reference/scripts.v3.yml @@ -3,7 +3,7 @@ info: title: Scripts version: '' description: |- - Inject client-side code onto a BigCommerce storefront. To learn more about scripts, see [Scripts API](/api-docs/store-management/scripts). + Add client-side code to a BigCommerce storefront page or associate a script with a channel. To learn more about scripts, see the [Scripts API](/docs/integrations/scripts) article. termsOfService: 'https://www.bigcommerce.com/terms' contact: name: BigCommerce @@ -36,29 +36,30 @@ paths: application/json: schema: $ref: '#/components/schemas/script_Post' - examples: {} + examples: + Script Source URL: + value: + name: Bootstrap + description: Build responsive websites + src: 'https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/js/bootstrap.min.js' + auto_uninstall: true + load_method: default + location: footer + visibility: all_pages + kind: src + consent_category: essential + HTML Script Tag: + value: + name: Bootstrap + description: Build responsive websites + html: '' + auto_uninstall: true + load_method: default + location: footer + visibility: all_pages + kind: script_tag + consent_category: essential required: true - x-examples: - Script Source URL: - name: Bootstrap - description: Build responsive websites - src: 'https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/js/bootstrap.min.js' - auto_uninstall: true - load_method: default - location: footer - visibility: all_pages - kind: src - consent_category: essential - HTML Script Tag: - name: Bootstrap - description: Build responsive websites - html: null - auto_uninstall: true - load_method: default - location: footer - visibility: all_pages - kind: script_tag - consent_category: essential responses: '200': description: '' @@ -66,7 +67,6 @@ paths: application/json: schema: $ref: '#/components/schemas/script_Response' - examples: {} '422': description: | This is the result of missing required fields, or of invalid data. See the response for more details. @@ -110,11 +110,19 @@ paths: **Read Only Fields** * uuid + **Limits** + * 50 scripts per channel. + **Notes** - * If kind is `src` –- Only the `src` property is needed, and you can optionally supply a `load_method`. The `html` field should not be specified. - * If kind is `script_tag` -- Only the `script_tag` is needed. The `src` field should not be specified. + * If the `kind` is `src`: + * Specify the `src` property. + * Optionally, you can supply a `load_method`. + * Do not specify the `html` field. + * If the `kind` is `script_tag`: + * Specify the `html` property. + * Do not specify the `src` field. * Each app can have 10 scripts installed. - * Multiple scripts can be created [per call](/api-docs/store-management/scripts#notes). + * Multiple scripts can be created [per call](/docs/integrations/scripts#notes). get: summary: Get All Scripts operationId: getScripts @@ -225,7 +233,6 @@ paths: application/json: schema: $ref: '#/components/schemas/script_Response' - examples: {} '404': description: | The resource was not found. @@ -311,7 +318,6 @@ paths: application/json: schema: $ref: '#/components/schemas/script_Response' - examples: {} '404': description: | The resource was not found. @@ -613,15 +619,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header schemas: @@ -678,7 +684,6 @@ components: description: | Link to the next page returned in the response. title: Collection Meta - x-internal: false Pagination: type: object description: 'Data about the response, including pagination and collection totals.' @@ -828,6 +833,11 @@ components: allOf: - type: object properties: + name: + type: string + description: The user-friendly name. + minLength: 1 + maxLength: 255 uuid: type: string format: uuid @@ -841,7 +851,6 @@ components: format: date-time description: The date on which this object was last updated. - $ref: '#/components/schemas/script_Base' - x-examples: {} x-internal: false script_Post: title: script_Post @@ -871,7 +880,7 @@ components: script_Response: type: object title: script_Response - description: 'For a list of all locations visit [Scripts Visibility](/api-docs/store-management/scripts#script-visibility-locations).' + description: 'For a list of all locations visit [Scripts Visibility](/docs/integrations/scripts#script-visibility-locations).' properties: data: $ref: '#/components/schemas/script_Full' @@ -881,7 +890,7 @@ components: script_responseCollection: type: object title: script_responseCollection - description: 'For a list of all locations visit [Scripts Visibility](/api-docs/store-management/scripts#script-visibility-locations).' + description: 'For a list of all locations visit [Scripts Visibility](/docs/integrations/scripts#script-visibility-locations).' properties: data: type: array @@ -889,20 +898,19 @@ components: $ref: '#/components/schemas/script_Full' meta: $ref: '#/components/schemas/CollectionMeta' - x-internal: false script_Base: type: object title: script_Base description: 'Script properties common to `post`, `put`, and `get` requests.' - x-internal: false - x-examples: {} properties: description: type: string description: The user-friendly description. html: type: string - description: An html string containing exactly one `script` tag. Only present if `kind` is `script_tag`. + description: An HTML string containing exactly one `script` tag. Present when the script `kind` is `script_tag`. + minLength: 0 + maxLength: 65536 src: type: string description: The `src` attribute of the script to load. Only present if `kind` is `src`. @@ -925,7 +933,7 @@ components: - footer visibility: type: string - description: "Which set of pages the script should load on. \n\nPlease note that you need to have `Checkout content` scope to use `all_pages` and `checkout`.\n\n- The current visibility options are `storefront`, `checkout`, `all_pages` and `order_confirmation`.\n\n `storefront`: All pages that are not `checkout` or `order_confirmation`.\n\n\t\t \nFor a list of all locations visit [Scripts Visibility](/api-docs/store-management/scripts#script-visibility-locations)." + description: "Which set of pages the script should load on. \n\nPlease note that you need to have `Checkout content` scope to use `all_pages` and `checkout`.\n\n- The current visibility options are `storefront`, `checkout`, `all_pages` and `order_confirmation`.\n\n `storefront`: All pages that are not `checkout` or `order_confirmation`.\n\n\t\t \nFor a list of all locations visit [Scripts Visibility](/docs/integrations/scripts#script-visibility-locations)." enum: - storefront - all_pages @@ -936,10 +944,9 @@ components: description: |- What type of script this is. - `src` - a `script` tag will be generated with its `src` attribute set to the value of `src`; For scripts that use the src url. By providing a path to the script, we can optimize and serve the script tag automatically for you. + `src` - For scripts that use the src URL. A `script` tag will be generated with its `src` attribute set to the value of the `src` property. When your app provides a path to the script, we can optimize and add the script automatically for you. The load_method can vary. - `script_tag` - The value of `html` will be injected directly onto the page. - For scripts which include a raw HTML script_tag to be inserted into the page. The load_method must be default. + `script_tag` - For scripts that include a raw HTML `script` tag-enclosed block of JavaScript. The value of `html` is added directly to the page. The load_method must be default. enum: - src - script_tag @@ -949,7 +956,7 @@ components: description: 'The client id of the API user that created this script, or blank if created by other means.' consent_category: type: string - description: 'Consent category for GDPR and CCPA compliance. Defaults to `uknown` when not specified. Scripts with an `uknown` consent category do not display on stores with customer cookie consent banners enabled. ' + description: Consent category for GDPR and CCPA compliance. Defaults to `unknown` when not specified. Scripts with an `unknown` consent category do not display on stores with customer cookie consent banners enabled. enum: - essential - functional diff --git a/reference/settings.v3.yml b/reference/settings.v3.yml index 2c1530301..fb2b89139 100644 --- a/reference/settings.v3.yml +++ b/reference/settings.v3.yml @@ -37,6 +37,7 @@ tags: - name: Favicon Image - name: Store Profile - name: Storefront Product + - name: Units of Measurement paths: '/settings/analytics': parameters: @@ -65,6 +66,7 @@ paths: - $ref: '#/components/parameters/Accept' - name: id in: path + description: Web Analytics Provider ID. required: true schema: type: integer @@ -72,12 +74,6 @@ paths: summary: Get a Web Analytics Provider description: Returns a single web analytics provider data for a default channel. parameters: - - name: id - in: path - description: Web Analytics Provider ID. - required: true - schema: - type: integer - $ref: '#/components/parameters/ChannelIdParam' responses: '200': @@ -105,12 +101,6 @@ paths: description: Updates a single web analytics provider data for a default channel. parameters: - $ref: '#/components/parameters/ContentType' - - name: id - in: path - description: Web Analytics Provider ID. - required: true - schema: - type: integer - $ref: '#/components/parameters/ChannelIdParam' requestBody: content: @@ -792,11 +782,12 @@ paths: tags: - Search Filters '/settings/store/locale': - parameters: - - $ref: '#/components/parameters/Accept' get: summary: Get Locale Settings description: Returns global locale settings. + parameters: + - $ref: '#/components/parameters/Accept' + - $ref: '#/components/parameters/ChannelIdParam' responses: '200': description: '' @@ -821,9 +812,14 @@ paths: - Store Locale put: summary: Update Locale Settings - description: Updates global locale settings. + description: |- + Updates global locale settings. + + Set a channel override by using the `channel_id` query parameter. To remove a channel override, set `null` for a field. The field then inherits the global value. parameters: + - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/ContentType' + - $ref: '#/components/parameters/ChannelIdParam' requestBody: content: application/json: @@ -1439,6 +1435,66 @@ paths: tags: - Inventory description: Update inventory settings + /settings/store/units-of-measurement: + get: + summary: Get Units of Measurement Settings + description: |- + Get settings for [units of measurements](https://support.bigcommerce.com/s/article/Store-Settings?language=en_US#physical). + tags: + - Units of Measurement + responses: + '200': + description: 'OK. When you request channel-level settings, `null` indicates that a channel does not have overrides.' + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/MeasurementUnitsSettings' + meta: + type: object + '422': + description: The provided settings could not be applied. See detailed errors in the response. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + parameters: + - $ref: '#/components/parameters/ChannelIdParam' + put: + summary: Update Units of Measurement Settings + description: |- + Update settings for [units of measurements](https://support.bigcommerce.com/s/article/Store-Settings?language=en_US#physical). + + The endpoint does not support partial updates. Provide all fields to update global or channel-level settings. + + Create channel-level settings, or overrides for a channel, using the `channel_id` query parameter. + + To delete overrides for a channel, supply `null` as a value for all fields. A channel then inherits global values. + + The endpoint does not support 'null' as a value for global-level settings. + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/MeasurementUnitsSettings' + responses: + '200': + description: 'OK. When you request channel-level settings, `null` indicates that a channel does not have overrides.' + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/MeasurementUnitsSettings' + meta: + type: object + parameters: + - $ref: '#/components/parameters/ChannelIdParam' + tags: + - Units of Measurement components: parameters: Accept: @@ -1638,8 +1694,8 @@ components: default: relevance enum: - relevance - - atoz - - ztoa + - alphaasc + - alphadesc title: ContentSortEnumValues x-internal: false DetailedErrors: @@ -1952,13 +2008,22 @@ components: enum: - order_placed - order_completed_or_shipped - description: Describes when stock levels are updated. + description: |- + Describes when stock levels are updated. + + Global settings apply when inventory changes through a [manual order](https://support.bigcommerce.com/s/article/Creating-a-Manual-Order?language=en_US). Settings for a channel apply when inventory changes through an order in a channel. These settings affect webhooks that trigger from order-related events, including [product](/docs/integrations/webhooks/events#products), [SKU](/docs/integrations/webhooks/events#skus), and [inventory](/docs/integrations/webhooks/events/inventory-location#inventory) webhooks. edit_order_stock_adjustment: type: boolean - description: Describes whether stock levels automatically adjust when you edit an order. + description: |- + Describes whether stock levels automatically adjust when you edit an order. + + Global settings apply when inventory changes through a [manual order](https://support.bigcommerce.com/s/article/Creating-a-Manual-Order?language=en_US). Settings for a channel apply when inventory changes through an order in a channel. These settings affect webhooks that trigger from order-related events, including [product](/docs/integrations/webhooks/events#products), [SKU](/docs/integrations/webhooks/events#skus), and [inventory](/docs/integrations/webhooks/events/inventory-location#inventory) webhooks. refund_order_stock_adjustment: type: boolean - description: Describes whether stock levels automatically adjust when you refund or cancel an order. + description: |- + Describes whether stock levels automatically adjust when you refund or cancel an order. + + Global settings apply when inventory changes through a [manual order](https://support.bigcommerce.com/s/article/Creating-a-Manual-Order?language=en_US). Settings for a channel apply when inventory changes through an order in a channel. These settings affect webhooks that trigger from order-related events, including [product](/docs/integrations/webhooks/events#products), [SKU](/docs/integrations/webhooks/events#skus), and [inventory](/docs/integrations/webhooks/events/inventory-location#inventory) webhooks. stock_level_display: type: string enum: @@ -1973,6 +2038,16 @@ components: hide_in_product_filtering: type: boolean description: 'Describes whether an option is hidden in product filtering. Applies when `option_out_of_stock_behavior` is set to `label_option`. ' + show_pre_order_stock_levels: + type: boolean + description: Describes whether pre-order stock levels are shown. + default: false + example: true + show_out_of_stock_message: + type: boolean + description: Describes whether out-of-stock messages are shown on product listing pages. + default: false + example: true Locale: description: 'The basic locale settings for a store, used to give shopper information about languages, countries, etc.' type: object @@ -2077,11 +2152,12 @@ components: - featured - bestselling - newest - - atoz - - ztoa - - highestprice - - lowestprice - - bestreviewed + - alphaasc + - alphadesc + - pricedesc + - priceasc + - avgcustomerreview + - relevance title: ProductSortEnumValues x-internal: false RobotsTxtSettings: @@ -2231,6 +2307,11 @@ components: type: boolean search_suggest: type: boolean + required: + - content_product_sort + - default_product_sort + - product_filtering_enabled + - search_suggest x-internal: false StorefrontSecuritySettings: type: object @@ -2282,6 +2363,40 @@ components: type: string title: '' x-internal: false + MeasurementUnitsSettings: + type: object + properties: + weight_measurement: + type: string + example: Ounces + enum: + - LBS + - Ounces + - KGS + - Grams + - Tonnes + length_measurement: + type: string + example: Inches + enum: + - Inches + - Centimeters + decimal_token: + type: string + example: '.' + thousands_token: + type: string + example: ',' + decimal_places: + type: integer + example: 2 + factoring_dimension: + type: string + example: depth + enum: + - depth + - height + - width responses: 200-storefront-product-settings: description: OK. `null` indicates that a particular field has not been overridden on a channel level when channel level settings are requested @@ -2310,7 +2425,7 @@ components: properties: '': type: string - example: 'Incorrect value [current__only], it should match one of: current_category_only,child_categories_if_category_empty,child_categories; Incorrect value [besling], it should match one of: featured,newest,bestselling,atoz,ztoa,bestreviewed,lowestprice,highestprice' + example: 'Incorrect value [current__only], it should match one of: current_category_only,child_categories_if_category_empty,child_categories; Incorrect value [besling], it should match one of: featured, newest, bestselling, alphaasc, alphadesc, avgcustomerreview, priceasc, pricedesc, relevance' minLength: 1 status: type: number @@ -2326,7 +2441,7 @@ components: x-examples: example-1: errors: - '': 'Incorrect value [], it should match one of: current_category_only,child_categories_if_category_empty,child_categories; Incorrect value [], it should match one of: featured,newest,bestselling,atoz,ztoa,bestreviewed,lowestprice,highestprice' + '': 'Incorrect value [], it should match one of: current_category_only,child_categories_if_category_empty,child_categories; Incorrect value [], it should match one of: featured, newest, bestselling, alphaasc, alphadesc, avgcustomerreview, priceasc, pricedesc, relevance' status: 422 title: JSON data is missing or invalid type: 'https://developer.bigcommerce.com/api-docs/getting-started/api-status-codes' @@ -2345,14 +2460,14 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header diff --git a/reference/shipping.v2.yml b/reference/shipping.v2.yml index e83d5560b..cf585cd16 100644 --- a/reference/shipping.v2.yml +++ b/reference/shipping.v2.yml @@ -162,7 +162,7 @@ paths: enabled: true 'Example 2: Zone is Selection of States in a Country': value: - - id: 2 + - id: 2 name: States in the U.S. type: state locations: @@ -786,7 +786,7 @@ paths: type: royalmail settings: {} enabled: true - handling_fees: + handling_fees: fixed_surcharge: "0" is_fallback: false - id: 35889344 @@ -794,7 +794,7 @@ paths: type: canadapost settings: {} enabled: true - handling_fees: + handling_fees: percentage_surcharge: "0" is_fallback: false operationId: getShippingMethodsZone @@ -1082,12 +1082,12 @@ paths: | Property | Type | Description | |:---------|:-----|:------------| - | default_cost | number | Default shipping cost, applied either as a percentage of the orderʼs total value or as a fixed amount. | + | default_cost | number | null | Default shipping cost, applied either as a percentage of the orderʼs total value or as a fixed amount. If default cost is not required, you can supply a value of null. | | default_cost_type | string | How the default shipping cost is calculated; either `percentage_of_total` or `fixed_amount`. | | range | number | Array of [range](#range) objects. The units for these ranges' `lower_limit` and `upper_limit` properties depend on the default units set in the storeʼs control panel. | Example request body: - + ```json { "name": "Rate per Weight", @@ -1117,9 +1117,8 @@ paths: | Property | Type | Description | |:---------|:-----|:------------| - | default_cost | number | Default shipping cost, applied either as a percentage of the orderʼs total value or as a fixed amount. | + | default_cost | number | null | Default shipping cost, applied either as a percentage of the orderʼs total value or as a fixed amount. If default cost is not required, you can supply a value of null. | | default_cost_type | string | How the default shipping cost is calculated; either `percentage_of_total` or `fixed_amount`. | - | include_order_total_taxes | boolean | Whether or not to include taxes on the orderʼs total value in the shipping cost calculation. | | range | number | Array of [range](#range) objects. The units for these ranges' `lower_limit` and `upper_limit` properties are values in the storeʼs currency. | Example request body: @@ -1133,7 +1132,6 @@ paths: "settings": { "default_cost": 12, "default_cost_type": "fixed_amount", - "include_order_total_taxes": 0, "range": [ { "lower_limit": 0, @@ -1184,7 +1182,7 @@ paths: "upper_limit": 20, "shipping_cost": 8 } - ``` + ``` summary: Create a Shipping Method tags: - Shipping Method @@ -1229,7 +1227,7 @@ paths: type: auspost settings: {} enabled: false - handling_fees: + handling_fees: fixed_surcharge: "0" is_fallback: false operationId: createAShippingMethod @@ -1296,7 +1294,7 @@ paths: | Name | Type | Description | | - | - | - | - | default_cost | number | Default shipping cost, applied either as a percentage of the orderʼs total value or as a fixed amount. | + | default_cost | number | null | Default shipping cost, applied either as a percentage of the orderʼs total value or as a fixed amount. If default cost is not required, you can supply a value of null. | | default_cost_type | string | How the default shipping cost is calculated; either `percentage_of_total` or `fixed_amount`. | | range | number | Array of [range](#range) objects. The units for these ranges' `lower_limit` and `upper_limit` properties depend on the default units set in the storeʼs control panel. | @@ -1331,9 +1329,8 @@ paths: | Name | Type | Description | | - | - | - | - | default_cost | number | Default shipping cost, applied either as a percentage of the orderʼs total value or as a fixed amount. | + | default_cost | number | null | Default shipping cost, applied either as a percentage of the orderʼs total value or as a fixed amount. If default cost is not required, you can supply a value of null. | | default_cost_type | string | How the default shipping cost is calculated; either `percentage_of_total` or `fixed_amount`. | - | include_order_total_taxes | boolean | Whether or not to include taxes on the orderʼs total value in the shipping cost calculation. | | range | number | Array of [range](#range) objects. The units for these ranges' `lower_limit` and `upper_limit` properties are values in the storeʼs currency. | #### JSON Example @@ -1347,7 +1344,6 @@ paths: "settings": { "default_cost": 12, "default_cost_type": "fixed_amount", - "include_order_total_taxes": 0, "range": [ { "lower_limit": 0, @@ -1466,7 +1462,7 @@ paths: type: weight settings: {} enabled: false - handling_fees: + handling_fees: percentage_surcharge: "0" is_fallback: false x-unitTests: [] @@ -1533,13 +1529,13 @@ paths: | Property | Type | Description | |:---------|:-----|:------------| - | default_cost | number | Default shipping cost, applied either as a percentage of the orderʼs total value or as a fixed amount. | + | default_cost | number | null | Default shipping cost, applied either as a percentage of the orderʼs total value or as a fixed amount. If default cost is not required, you can supply a value of null. | | default_cost_type | string | How the default shipping cost is calculated; either `percentage_of_total` or `fixed_amount`. | | range | number | Array of [range](#range) objects. The units for these ranges' `lower_limit` and `upper_limit` properties depend on the default units set in the storeʼs control panel. | Example response: - + ```json { "name": "Rate per Weight", @@ -1569,9 +1565,8 @@ paths: | Property | Type | Description | |:---------|:-----|:------------| - | default_cost | number | Default shipping cost, applied either as a percentage of the orderʼs total value or as a fixed amount. | + | default_cost | number | null | Default shipping cost, applied either as a percentage of the orderʼs total value or as a fixed amount. If default cost is not required, you can supply a value of null. | | default_cost_type | string | How the default shipping cost is calculated; either `percentage_of_total` or `fixed_amount`. | - | include_order_total_taxes | boolean | Whether or not to include taxes on the orderʼs total value in the shipping cost calculation. | | range | number | Array of [range](#range) objects. The units for these ranges' `lower_limit` and `upper_limit` properties are values in the storeʼs currency. | Example response: @@ -1585,7 +1580,6 @@ paths: "settings": { "default_cost": 12, "default_cost_type": "fixed_amount", - "include_order_total_taxes": 0, "range": [ { "lower_limit": 0, @@ -1636,7 +1630,7 @@ paths: "shipping_cost": 8 } ``` - + summary: Update a Shipping Method tags: - Shipping Method @@ -1678,7 +1672,7 @@ paths: type: endicia settings: {} enabled: false - handling_fees: + handling_fees: fixed_surcharge: "0" is_fallback: false x-unitTests: [] @@ -1887,7 +1881,7 @@ paths: { "carrier_id" : "royalmail", "connection" : { - + } } ``` @@ -1904,6 +1898,32 @@ paths: Royal Mail has no connection object properties. + ### Shipping Provider API + + Please note that this endpoint is not intended for adding connection settings. + + Its purpose is solely to establish a connection between your BigCommerce store and the carrier. If the carrier has no connection settings configured, please leave the connection property empty. However, if the carrier already has connection settings configured, you can utilize this endpoint to establish the connection using the existing connection properties. + + PUT or POST example request when your carrier is not configured with any connection settings: + + ```json filename="No connection settings configured" showLineNumbers copy + { + "carrier_id" : "carrier_{your_carrier_id}", + "connection" : {} + } + ``` + + PUT or POST example request when your carrier is configured with connection settings: + + ```json filename="Connection settings configured" showLineNumbers copy + { + "carrier_id" : "carrier_{your_carrier_id}", + "connection" : { + "your_configured_key_1": "value_1", + "your_configured_key_2": "value_2 + } + } + ``` ### Zoom2U @@ -2060,15 +2080,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header schemas: @@ -2091,7 +2111,6 @@ components: title: Shipping Provider type: string enum: - - '``' - fedex - auspost - canadapost diff --git a/reference/shipping.v3.yml b/reference/shipping.v3.yml index f7dbb125f..3158f23a4 100644 --- a/reference/shipping.v3.yml +++ b/reference/shipping.v3.yml @@ -54,7 +54,7 @@ paths: parameters: - in: query name: 'product_id:in' - description: 'A comma-separated list of product IDs. For more information, see [Filtering](/api-docs/getting-started/filtering).' + description: 'A comma-separated list of product IDs. For more information, see [Filtering](/docs/start/about/common-query-params).' style: form explode: false schema: @@ -273,7 +273,7 @@ components: schema: $ref: '#/components/schemas/error_Full' 429_Too_Many_Requests: - description: 'When an OAuth client exceeds the [rate limit](/api-docs/getting-started/best-practices#api-rate-limits) for API requests to a store.' + description: 'When an OAuth client exceeds the [rate limit](/docs/start/best-practices#api-rate-limits) for API requests to a store.' content: application/json: schema: @@ -305,15 +305,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header schemas: diff --git a/reference/shipping_provider.yml b/reference/shipping_provider.yml index db293a106..2b2190c06 100644 --- a/reference/shipping_provider.yml +++ b/reference/shipping_provider.yml @@ -3,13 +3,13 @@ info: version: '' title: Shipping Providers description: |- - Implement endpoints consumed by BigCommerce for custom shipping integrations. To learn more, see [Shipping Provider API Overview](/api-docs/store-management/shipping/shipping-provider-api). + Implement endpoints consumed by BigCommerce for custom shipping integrations. To learn more, see [Shipping Provider API Overview](/docs/integrations/shipping). ## Authentication This specification file describes API requests BigCommerce will make to a registered shipping carrierʼs server to check connection options and retrieve rates. As such, the method of authentication is determined by the carrier server. - For more, see [developer-configured authentication](/api-docs/getting-started/authentication#developer-configured-authentication) for provider APIs. + For more, see [developer-configured authentication](/docs/start/authentication#developer-configured-authentication) for provider APIs. ## Subresources @@ -22,10 +22,10 @@ info: ## Additional Information ### Webhooks - - [Shipment](/api-docs/store-management/webhooks/webhook-events#shipment) + - [Shipments](/docs/integrations/webhooks/events#shipments) ### Related API Resources - - [Shipping Provider](/docs/apps-api/shipping) + - [Shipping Provider](/docs/rest-contracts/shipping) - [Shipping V2 API](/docs/rest-management/shipping-v2) termsOfService: 'https://www.bigcommerce.com/terms' contact: @@ -627,7 +627,7 @@ components: description: The value associated with the meta field. namespace: type: string - description: 'The namespace associated with metafields for [products](/docs/rest-management/catalog/product-metafields#create-a-product-metafield) and [product variants](/docs/rest-management/catalog/product-variants-metafields). Save the metafield namespace using the format `shipping_carrier_{yourCarrierId}`; otherwise, it will not be recognized as a valid attribute.' + description: 'The namespace associated with metafields for [products](/docs/rest-catalog/products/metafields#create-a-product-metafield) and [product variants](/docs/rest-catalog/product-variants/metafields). Save the metafield namespace using the format `shipping_carrier_{yourCarrierId}`; otherwise, it will not be recognized as a valid attribute.' resource_type: type: string enum: @@ -853,7 +853,7 @@ components: type: string maxLength: 50 discounted_cost: - description: Value object for a money amount. + description: Value object for a money amount. Optional field; merchants may request features. type: object properties: currency: @@ -869,6 +869,7 @@ components: dispatch_date: type: string format: date + description: Date at which carrier dispatches to the shipping destination. Optional field; merchants may request features. transit_time: type: object properties: @@ -972,7 +973,7 @@ components: type: string maxLength: 50 discounted_cost: - description: Value object for a money amount. + description: Value object for a money amount. Optional field; merchants may request features. type: object properties: currency: @@ -988,6 +989,7 @@ components: dispatch_date: type: string format: date + description: Date at which carrier dispatches to the shipping destination. Optional field; merchants may request features. transit_time: type: object properties: @@ -1135,7 +1137,7 @@ components: description: The value associated with the product or product variant meta field. namespace: type: string - description: 'The namespace associated with metafields for [products](docs/rest-management/catalog/product-metafields) and [product variants](/docs/rest-management/catalog/product-variants-metafields). Save the metafield namespace using the format `shipping_carrier_{yourCarrierId}`; otherwise, it will not be recognized as a valid attribute.' + description: 'The namespace associated with metafields for [products](/docs/rest-catalog/products/metafields) and [product variants](/docs/rest-catalog/product-variants/metafields). Save the metafield namespace using the format `shipping_carrier_{yourCarrierId}`; otherwise, it will not be recognized as a valid attribute.' resource_type: type: string enum: @@ -1252,7 +1254,7 @@ components: type: string maxLength: 50 discounted_cost: - description: Value object for a money amount. + description: Value object for a money amount. Optional field; merchants may request features. type: object properties: currency: @@ -1268,6 +1270,7 @@ components: dispatch_date: type: string format: date + description: Date at which carrier dispatches to the shipping destination. Optional field; merchants may request features. transit_time: type: object properties: @@ -1318,7 +1321,7 @@ components: description: The value associated with the product or product variant meta field. namespace: type: string - description: 'The namespace associated with metafields for [products](docs/rest-management/catalog/product-metafields) and [product variants](/docs/rest-management/catalog/product-variants-metafields). Save the metafield namespace using the format `shipping_carrier_{yourCarrierId}`; otherwise, it will not be recognized as a valid attribute.' + description: 'The namespace associated with metafields for [products](/docs/rest-catalog/products/metafields) and [product variants](/docs/rest-catalog/product-variants/metafields). Save the metafield namespace using the format `shipping_carrier_{yourCarrierId}`; otherwise, it will not be recognized as a valid attribute.' resource_type: type: string description: Resource type associated with the product or product variant meta field. Currently, the only values available are 'product' or 'variant'. @@ -1854,7 +1857,7 @@ components: description: The value associated with the meta field. namespace: type: string - description: 'The namespace associated with a [product](docs/rest-management/catalog/product-metafields) or [product variant](/docs/rest-management/catalog/product-variants-metafields) metafields. You should save a metafield namespace under this format `shipping_carrier_{yourCarrierId}`; otherwise, you will not be able to recognize it as an attribute.' + description: 'The namespace associated with a [product](/docs/rest-catalog/products/metafields) or [product variant](/docs/rest-catalog/product-variants/metafields) metafields. You should save a metafield namespace under this format `shipping_carrier_{yourCarrierId}`; otherwise, you will not be able to recognize it as an attribute.' resource_type: type: string enum: @@ -1915,4 +1918,4 @@ components: type: string description: The value of a [shipping address](/docs/rest-management/orders/order-shipping-addresses#get-a-shipping-address) form field. Depending on the form field, this could be a user-defined value or the value of a hidden input. title: Form Field Value - \ No newline at end of file + diff --git a/reference/sites.v3.yml b/reference/sites.v3.yml index 4e2730f30..0037a7f4f 100644 --- a/reference/sites.v3.yml +++ b/reference/sites.v3.yml @@ -7,7 +7,7 @@ info: ## [Sites](/docs/rest-management/sites) - Sites link [headless storefronts](/api-docs/storefronts/developers-guide-headless) to sales [channels](/docs/rest-management/channels). To [create a site](/docs/rest-management/sites#create-a-site), send a `POST` request to `/stores/{{STORE_HASH}}/v3/sites`. + Sites link [headless storefronts](/docs/storefront/headless) to sales [channels](/docs/rest-management/channels). To [create a site](/docs/rest-management/sites#create-a-site), send a `POST` request to `/stores/{{STORE_HASH}}/v3/sites`. ```http POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/sites @@ -43,7 +43,7 @@ info: ## Site routes - [Site routes](/docs/rest-management/sites/site-routes) tell BigCommerce how to link to pages on a [headless storefront](/api-docs/storefronts/developers-guide-headless). To [create a route](/docs/rest-management/sites/site-routes#create-a-site-route) for a [site](#sites), send a `POST` request to `/stores/{{STORE_HASH}}/v3/sites/{site_id}/routes`. + [Site routes](/docs/rest-management/sites/site-routes) tell BigCommerce how to link to pages on a [headless storefront](/docs/storefront/headless). To [create a route](/docs/rest-management/sites/site-routes#create-a-site-route) for a [site](#sites), send a `POST` request to `/stores/{{STORE_HASH}}/v3/sites/{site_id}/routes`. ```http POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/sites/{site_id}/routes @@ -111,8 +111,8 @@ info: ### Related resources * [Channels and Listings Reference](/docs/rest-management/channels) - * [Channels Overview](/api-docs/channels/overview) - * [Building Headless Storefronts Guide](/api-docs/storefronts/developers-guide-headless) + * [Channels Overview](/docs/integrations/channels) + * [Building Headless Storefronts Guide](/docs/storefront/headless) termsOfService: 'https://www.bigcommerce.com/terms' contact: name: BigCommerce @@ -166,13 +166,13 @@ paths: $ref: '#/components/responses/504_GatewayTimeout' tags: - Sites - description: 'Create a site that links a [headless storefront](/api-docs/storefronts/developers-guide-headless) to a sales [channel](/docs/rest-management/channels).' + description: 'Create a site that links a [headless storefront](/docs/storefront/headless) to a sales [channel](/docs/rest-management/channels).' get: responses: '200': $ref: '#/components/responses/site_RespCollection' summary: Get Sites - description: 'Get sites linked to a [headless storefront](/api-docs/storefronts/developers-guide-headless) sales channels.' + description: 'Get sites linked to a [headless storefront](/docs/storefront/headless) sales channels.' tags: - Sites parameters: @@ -332,7 +332,7 @@ paths: tags: - Site Routes description: |- - Create routes that tell BigCommerce how to link to pages on a [headless storefront](/api-docs/storefronts/developers-guide-headless). + Create routes that tell BigCommerce how to link to pages on a [headless storefront](/docs/storefront/headless). ## Usage Notes * For a list of supported route types, see [Route types](/docs/rest-management/sites#route-types). @@ -1260,15 +1260,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header parameters: diff --git a/reference/store_content.v2.yml b/reference/store_content.v2.yml index 666ada14b..93be79c3b 100644 --- a/reference/store_content.v2.yml +++ b/reference/store_content.v2.yml @@ -5,7 +5,9 @@ info: Manage blog posts, blog tags, content pages, and redirects. > #### Warning - > * Redirects V2 are deprecated; use [V3 Redirects](/docs/rest-management/redirects) instead. + > **Deprecations** + > * Redirects V2 are deprecated; use [Redirects V3](/docs/rest-management/redirects) instead. + > * Pages V2 are deprecated; use [Pages V3](/docs/rest-content/pages) instead. version: '' termsOfService: 'https://www.bigcommerce.com/terms' contact: @@ -147,7 +149,7 @@ paths: title: Your first blog post! url: /your-first-blog-post/ preview_url: /your-first-blog-post/ - body: "<p><strong>Welcome to your blog!</strong><br> A blog is a great place to share details on your products, business and whatever else you think your shoppers might like to hear from you. You can include photos in your blog posts and even videos. For ideas and inspiration on how to structure your blog, take a look at the BigCommerce <a href='http://blog.bigcommerce.com/' target='_blank' rel='nofollow'>ecommerce blog</a>.</p><p><strong>How can I delete this post?</strong><br>To delete this post and add your own, login to your <a href='/admin' target='_blank'>admin area</a> and go to Storefront > Blog in the left hand menu.</p><p><strong>Powered by Bigcommerce</strong><br>Your website, online store and blog are powered by Bigcommerce <a href='http://www.bigcommerce.com/' target='_blank' rel='nofollow'>ecommerce software</a>. It includes everything you need to run a beautiful online store including <a href='http://www.bigcommerce.com/templates/' target='_blank' rel='nofollow'>ecommerce website templates</a>, <a href='http://www.bigcommerce.com/features/hosting/' target='_blank' rel='nofollow'>ecommerce hosting</a>, an <a href='http://www.bigcommerce.com/features/setup/' target='_blank' rel='nofollow'>online shopping cart</a> and more.</p>" + body: "<p><strong>Welcome to your blog!</strong><br> A blog is a great place to share details on your products, business and whatever else you think your shoppers might like to hear from you. You can include photos in your blog posts and even videos. For ideas and inspiration on how to structure your blog, take a look at the BigCommerce <a href='http://blog.bigcommerce.com/' target='_blank' rel='nofollow'>ecommerce blog</a>.</p><p><strong>How can I delete this post?</strong><br>To delete this post and add your own, login to your <a href='/admin' target='_blank'>admin area</a> and go to Storefront > Blog in the left hand menu.</p><p><strong>Powered by BigCommerce</strong><br>Your website, online store and blog are powered by BigCommerce <a href='http://www.bigcommerce.com/' target='_blank' rel='nofollow'>ecommerce software</a>. It includes everything you need to run a beautiful online store including <a href='http://www.bigcommerce.com/templates/' target='_blank' rel='nofollow'>ecommerce website templates</a>, <a href='http://www.bigcommerce.com/features/hosting/' target='_blank' rel='nofollow'>ecommerce hosting</a>, an <a href='http://www.bigcommerce.com/features/setup/' target='_blank' rel='nofollow'>online shopping cart</a> and more.</p>" tags: - Blog - SEO @@ -343,7 +345,7 @@ paths: author: BigCommerce thumbnail_path: '' '207': - description: 'Multiple operations have taken place and the status for each operation can be viewed in the body of the response. Typically indicates that a partial failure has occured, such as when a `POST` or `PUT` request is successful, but saving the URL has failed.' + description: 'Multiple operations have taken place and the status for each operation can be viewed in the body of the response. Typically indicates that a partial failure has occurred, such as when a `POST` or `PUT` request is successful, but saving the URL has failed.' content: application/json: schema: @@ -381,10 +383,17 @@ paths: parameters: - $ref: '#/components/parameters/Accept' get: + deprecated: true tags: - Pages summary: Get All Pages - description: 'Returns a list of *Pages*. Default sorting is by auto-generated ID from oldest to newest. This endpoint is deprecated. ' + description: | + Returns a list of *Pages*. Default sorting is by auto-generated ID from oldest to newest. + + > #### Warning + > **Deprecated** + > * This API operation is deprecated. Avoid using this API operation if possible. It will be removed in a future version. + > * To get one or more pages, use Pages V3ʼs [Get pages](/docs/rest-content/pages#get-pages) endpoint. To get a single page, use Pages V3ʼs [Get a page](/docs/rest-content/pages#get-a-page) endpoint. operationId: getAllPages parameters: - name: page @@ -432,13 +441,13 @@ paths: meta_title: '' search_keywords: '' meta_keywords: '' - deprecated: true post: + deprecated: true tags: - Pages summary: Create a Page description: |- - Creates a *Page*. The payload limit is 1MB. This endpoint is deprecated. + Creates a *Page*. The request payload limit is 1MB. **Required Fields** * `type` @@ -453,6 +462,11 @@ paths: ## Content Type The default value for `content_type` is `text/html`; however, if `page_type` is set to `raw`, `content_type` can be changed to `text/javascript` or `application/json`. Updating this field allows you to place a JavaScript or a JSON file in the root directory. + + > #### Warning + > **Deprecated** + > * This API operation is deprecated. Avoid using this API operation if possible. It will be removed in a future version. + > * To create one or more pages, use Pages V3ʼs [Create pages](/docs/rest-content/pages#create-pages) endpoint. operationId: createAPage parameters: - $ref: '#/components/parameters/ContentType' @@ -514,12 +528,11 @@ paths: search_keywords: '' meta_keywords: '' '207': - description: 'Multiple operations have taken place and the status for each operation can be viewed in the body of the response. Typically indicates that a partial failure has occured, such as when a `POST` or `PUT` request is successful, but saving the URL has failed.' + description: 'Multiple operations have taken place and the status for each operation can be viewed in the body of the response. Typically indicates that a partial failure has occurred, such as when a `POST` or `PUT` request is successful, but saving the URL has failed.' content: application/json: schema: type: object - deprecated: true x-codegen-request-body-name: body '/pages/{id}': parameters: @@ -533,10 +546,17 @@ paths: exclusiveMinimum: false type: integer get: + deprecated: true tags: - Pages summary: Get A Page - description: Returns a *Page*. This endpoint is deprecated. + description: | + Returns a *Page*. + + > #### Warning + > **Deprecated** + > * This API operation is deprecated. Avoid using this API operation if possible. It will be removed in a future version. + > * To get a single page, use Pages V3ʼs [Get a page](/docs/rest-content/pages#get-a-page) endpoint. operationId: getAPage responses: '200': @@ -565,16 +585,21 @@ paths: link: '' mobile_body: '0' url: /rss-syndication/ - deprecated: true put: + deprecated: true tags: - Pages summary: Update a Page description: |- - Updates a *Page*. The payload limit is 1MB. This endpoint is deprecated. + Updates a *Page*. The request payload limit is 1MB. **Read Only Fields** * id + + > #### Warning + > **Deprecated** + > * This API operation is deprecated. Avoid using this API operation if possible. It will be removed in a future version. + > * To update multiple pages, use Pages V3ʼs [Update pages](/docs/rest-content/pages#update-pages) endpoint. To update a single page, use Pages V3ʼs [Update a page](/docs/rest-content/pages#update-a-page) endpoint. operationId: updateAPage parameters: - $ref: '#/components/parameters/ContentType' @@ -612,28 +637,34 @@ paths: mobile_body: '' url: /shipping-returns/ '207': - description: 'Multiple operations have taken place and the status for each operation can be viewed in the body of the response. Typically indicates that a partial failure has occured, such as when a `POST` or `PUT` request is successful, but saving the URL has failed.' + description: 'Multiple operations have taken place and the status for each operation can be viewed in the body of the response. Typically indicates that a partial failure has occurred, such as when a `POST` or `PUT` request is successful, but saving the URL has failed.' content: application/json: schema: type: object - deprecated: true x-codegen-request-body-name: body delete: + deprecated: true tags: - Pages summary: Delete a Page - description: 'Deletes a *Page*. This endpoint is deprecated. ' + description: | + Deletes a *Page*. + + > #### Warning + > **Deprecated** + > * This API operation is deprecated. Avoid using this API operation if possible. It will be removed in a future version. + > * To delete multiple pages, use Pages V3ʼs [Delete pages](/docs/rest-content/pages#delete-pages) endpoint. To delete a single page, use Pages V3ʼs [Delete a page](/docs/rest-content/pages#delete-a-page) endpoint. operationId: deleteAPage responses: '204': description: '' content: {} - deprecated: true '/redirects': parameters: - $ref: '#/components/parameters/Accept' get: + deprecated: true tags: - Redirects summary: Get All Redirects @@ -642,8 +673,8 @@ paths: > #### Warning > **Deprecated** - >* This API operation is deprecated. Avoid using this API operation if possible. It will be removed in a future version. - >* For the most up-to-date version of this API, see [Get Redirects v3](/docs/rest-management/redirects#get-redirects) to manage redirect URLs. + > * This API operation is deprecated. Avoid using this API operation if possible. It will be removed in a future version. + > * To get redirect URLs, use Redirects V3ʼs [Get redirects](/docs/rest-management/redirects#get-redirects) endpoint. operationId: getAListofRedirects parameters: - name: page @@ -671,7 +702,6 @@ paths: $ref: '#/components/schemas/redirect' Response Schema: example: '' - deprecated: true post: tags: - Redirects @@ -690,7 +720,7 @@ paths: > #### Warning > **Deprecated** > * This API operation is deprecated. Avoid using this API operation if possible. It will be removed in a future version. - > * For the most up-to-date version of this API, see [Upsert Redirects v3](/docs/rest-management/redirects#upsert-redirects) to upsert new redirect data. + > * To upsert new redirect data, use Redirects V3ʼs [Upsert redirects](/docs/rest-management/redirects#upsert-redirects) endpoint. operationId: createARedirect parameters: - $ref: '#/components/parameters/ContentType' @@ -716,6 +746,7 @@ paths: url: 'http://store.example.com/mens' x-codegen-request-body-name: body delete: + deprecated: true tags: - Redirects summary: Delete All Redirects @@ -724,9 +755,9 @@ paths: > #### Warning - >**Deprecated** + > **Deprecated** > * This API operation is deprecated. Avoid using this API operation if possible. It will be removed in a future version. - > * For the most up-to-date version of this API, see [Delete Redirects v3](/docs/rest-management/redirects#delete-redirects) to delete redirect URLs. + > * To delete redirect URLs, use Redirects V3ʼs [Delete redirects](/docs/rest-management/redirects#delete-redirects) endpoint. operationId: deleteAllRedirects responses: '204': @@ -744,6 +775,7 @@ paths: exclusiveMinimum: false type: integer get: + deprecated: true tags: - Redirects summary: Get a Redirect @@ -751,9 +783,9 @@ paths: Returns a single *Redirect URL*. > #### Warning - >**Deprecated** + > **Deprecated** > * This API operation is deprecated. Avoid using this API operation if possible. It will be removed in a future version. - > * For the most up-to-date version of this API, see [Get Redirects v3](/docs/rest-management/redirects#get-redirects) to get a redirect URL. + > * To get a redirect URL, use Redirects V3ʼs [Get redirects](/docs/rest-management/redirects#get-redirects) endpoint. operationId: getARedirectURL responses: '200': @@ -769,7 +801,6 @@ paths: type: product ref: 111 url: 'http://store-url.mybigcommerce.com/towels/bath-towels/hand-towels/' - deprecated: true put: tags: - Redirects @@ -788,7 +819,7 @@ paths: > #### Warning > **Deprecated** > * This API operation is deprecated. Avoid using this API operation if possible. It will be removed in a future version. - > * For the most up-to-date version of this API, see [Upsert Redirects v3](/docs/rest-management/redirects#upsert-redirects) to update redirect data. + > * To update redirect data, use Redirects V3ʼs [Upsert redirects](/docs/rest-management/redirects#upsert-redirects) endpoint. operationId: updateARedirectURL parameters: - $ref: '#/components/parameters/ContentType' @@ -858,8 +889,8 @@ paths: > #### Warning > **Deprecated** - > This API operation is deprecated. Avoid using this API operation if possible. It will be removed in a future version. - > For the most up-to-date version of this API, see [Delete Redirects v3](/docs/rest-management/redirects#delete-redirects) to delete a redirect URL. + > * This API operation is deprecated. Avoid using this API operation if possible. It will be removed in a future version. + > * To delete a redirect URL, use Redirects V3ʼs [Delete redirects](/docs/rest-management/redirects#delete-redirects) endpoint. operationId: deleteARedirect responses: '204': @@ -869,6 +900,7 @@ paths: parameters: - $ref: '#/components/parameters/Accept' get: + deprecated: true tags: - Redirects summary: Get a Count of Redirects @@ -878,7 +910,7 @@ paths: > #### Warning > **Deprecated** > * This API operation is deprecated. Avoid using this API operation if possible. It will be removed in a future version. - > * For the most up-to-date version of this API, see [Get Redirects v3](/docs/rest-management/redirects#get-redirects) to get a count of redirects. + > * To get a count of redirects, use the `meta` object data returned with the Redirects V3ʼs [Get redirects](/docs/rest-management/redirects#get-redirects) endpoint. operationId: getACountOfRedirects responses: '200': @@ -889,7 +921,6 @@ paths: $ref: '#/components/schemas/count_Response' example: count: 27 - deprecated: true components: parameters: Accept: @@ -1506,7 +1537,7 @@ components: description: Comma-separated list of SEO-relevant keywords to include in the page’s `<meta/>` element. feed: type: string - description: If page type is `rss_feed` the n this field is visisble. Required in POST required for `rss page` type. + description: If page type is `rss_feed` then this field is visible. Required in POST required for `rss page` type. link: type: string description: If page type is `link` this field is returned. Required in POST to create a `link` page. @@ -1597,7 +1628,7 @@ components: description: Comma-separated list of SEO-relevant keywords to include in the page’s `<meta/>` element. feed: type: string - description: If page type is `rss_feed` then this field is visisble. + description: If page type is `rss_feed` then this field is visible. link: type: string description: If page type is `link` this field is returned. @@ -1623,14 +1654,14 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header diff --git a/reference/store_information.v2.yml b/reference/store_information.v2.yml index d75c6d8a0..985533056 100644 --- a/reference/store_information.v2.yml +++ b/reference/store_information.v2.yml @@ -197,15 +197,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header schemas: diff --git a/reference/store_logs.v3.yml b/reference/store_logs.v3.yml index 334f19b1b..5dd8675b4 100644 --- a/reference/store_logs.v3.yml +++ b/reference/store_logs.v3.yml @@ -110,6 +110,16 @@ paths: in: query name: 'id:in' description: 'Query parameter that lets you filter by a list of log IDs, as a CSV. For example ?id:in=3,4,6' + - schema: + type: string + in: query + name: 'date_created:min' + description: 'Query parameter that lets you filter by the minimum date created in [Unix time](https://www.unixtimestamp.com/), for example, `?date_created:min=1657688400`. Returns logs created after this date.' + - schema: + type: string + in: query + name: 'date_created:max' + description: 'Query parameter that lets you filter by the maximum date created in [Unix time](https://www.unixtimestamp.com/), for example, `?date_created:min=1658379600`. Returns logs created before this date.' parameters: [] components: schemas: @@ -210,15 +220,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header tags: diff --git a/reference/storefront_tokens.v3.yml b/reference/storefront_tokens.v3.yml index a53e24149..c26f34cbc 100644 --- a/reference/storefront_tokens.v3.yml +++ b/reference/storefront_tokens.v3.yml @@ -2,11 +2,11 @@ openapi: '3.0.1' info: title: Storefront Token description: |- - Get and manage tokens used to authenticate cross-origin requests to the [GraphQL Storefront API](/api-docs/storefront/graphql/graphql-storefront-api-overview). + Get and manage tokens used to authenticate cross-origin requests to the [GraphQL Storefront API](/docs/storefront/graphql). - ## [API tokens](/docs/storefront-auth/tokens#create-a-token) + ## [API tokens](/docs/rest-authentication/tokens#create-a-token) - Generate tokens (JWT) for authenticating cross-origin requests to the [GraphQL Storefront API](/api-docs/storefront/graphql/graphql-storefront-api-overview). To [create a token](/docs/storefront-auth/tokens#create-a-token), send a `POST` request to `/stores/{{STORE_HASH}}/v3/storefront/api-token`. + Generate tokens (JWT) for authenticating cross-origin requests to the [GraphQL Storefront API](/docs/storefront/graphql). To [create a token](/docs/rest-authentication/tokens#create-a-token), send a `POST` request to `/stores/{{STORE_HASH}}/v3/storefront/api-token`. ```http POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/storefront/api-token @@ -26,10 +26,10 @@ info: |Property|Type|Description| |-|-|-| |`channel_id`|int| Must be a valid channel ID on the store (required) | - |`expires_at`|int| Unix timestamp (required) | + |`expires_at`|int| Unix timestamp in seconds (required). Does not support milliseconds, microseconds, or nanoseconds. | |`allowed_cors_origins`|array[str]| Allowed origins for cross origin requests (required) | - [**Response:**](/docs/storefront-auth/tokens#create-a-token) + [**Response:**](/docs/rest-authentication/tokens#create-a-token) ```json { @@ -42,9 +42,9 @@ info: - ## [Customer impersonation tokens](/docs/storefront-auth/tokens/customer-impersonation-token#create-a-token) + ## [Customer impersonation tokens](/docs/rest-authentication/tokens/customer-impersonation-token#create-a-token) - Generate tokens for use in server-to-server requests to the [GraphQL Storefront API](/api-docs/storefront/graphql/graphql-storefront-api-overview#customer-impersonation-tokens). To [create a customer impersonation token](/docs/storefront-auth/tokens/customer-impersonation-token#create-a-token), send a `POST` request to `/v3/storefront/api-token-customer-impersonation`. + Generate tokens that can make queries from the perspective of a particular customer in headless or server-side code using the [GraphQL Storefront API](/docs/storefront/graphql#customer-impersonation-tokens). To [create a customer impersonation token](/docs/rest-authentication/tokens/customer-impersonation-token#create-a-token), send a `POST` request to `/v3/storefront/api-token-customer-impersonation`. ```http POST https://api.bigcommerce.com/stores/{STORE_HASH}/v3/storefront/api-token-customer-impersonation @@ -53,7 +53,7 @@ info: Content-Type: application/json ``` - [**Response:**](/docs/storefront-auth/tokens/customer-impersonation-token#create-a-token) + [**Response:**](/docs/rest-authentication/tokens/customer-impersonation-token#create-a-token) ```json { @@ -65,7 +65,7 @@ info: } ``` - Customer impersonation token authenticated requests made to the GraphQL API receive store information from the perspective of the customer with the ID specified in the `X-Bc-Customer-Id` header sent with the GraphQL `POST` request. Pricing, product availability, customer account, and customer details will be reflected. Consider this sample request using a [customer impersonation token](/docs/storefront-auth/tokens/customer-impersonation-token#create-a-token) to run a request in the context of customer ID `123`. + Customer impersonation token authenticated requests made to the GraphQL API receive store information from the perspective of the customer with the ID specified in the `X-Bc-Customer-Id` header sent with the GraphQL `POST` request. Pricing, product availability, customer account, and customer details will be reflected. Consider this sample request using a [customer impersonation token](/docs/rest-authentication/tokens/customer-impersonation-token#create-a-token) to run a request in the context of customer ID `123`. ```http POST https://store.example.com/graphql @@ -85,7 +85,7 @@ info: ## Revoking tokens - To [revoke a token](/docs/storefront-auth/tokens#revoke-a-token), send a `DELETE` request to `/v3/storefront/api-token`. + To [revoke a token](/docs/rest-authentication/tokens#revoke-a-token), send a `DELETE` request to `/v3/storefront/api-token`. ```http DELETE /stores/{{STORE_HASH}}/v3/storefront/api-token-customer-impersonation @@ -96,7 +96,7 @@ info: ## Additional information - * [GraphQL API Overview](/api-docs/storefront/graphql/graphql-storefront-api-overview) + * [GraphQL API Overview](/docs/storefront/graphql) termsOfService: 'https://www.bigcommerce.com/terms' contact: name: BigCommerce @@ -190,7 +190,7 @@ paths: - Customer Impersonation Token summary: Create a Token description: |- - Returns a Storefront API token that allows your application to impersonate customers when making GraphQL `POST` requests. For more information on how to use the returned token, see [customer impersonation tokens](/docs/storefront-auth/tokens/customer-impersonation-token#create-a-token). + Returns a Storefront API token that allows your application to impersonate customers when making GraphQL `POST` requests. For more information on how to use the returned token, see [customer impersonation tokens](/docs/rest-authentication/tokens/customer-impersonation-token#create-a-token). **Required Scopes** * `Manage` `Storefront API Customer Impersonation Tokens` @@ -250,7 +250,7 @@ components: example: 1 expires_at: type: integer - description: Unix timestamp (UTC time) defining when the token should expire. + description: Unix timestamp (UTC time) defining when the token should expire. Supports seconds, but does not support milliseconds, microseconds, or nanoseconds. example: 1885635176 minimum: 0 required: @@ -342,15 +342,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). name: X-Auth-Token in: header diff --git a/reference/subscribers.v3.yml b/reference/subscribers.v3.yml index f0611f1d2..715f53778 100644 --- a/reference/subscribers.v3.yml +++ b/reference/subscribers.v3.yml @@ -905,15 +905,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header diff --git a/reference/subscriptions.sf.yml b/reference/subscriptions.sf.yml index d5c1b3202..e5eb799e0 100644 --- a/reference/subscriptions.sf.yml +++ b/reference/subscriptions.sf.yml @@ -4,15 +4,15 @@ info: description: |- Manage newsletter and marketing email subscriptions on the storefront. - For info about API accounts, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). + For info about API accounts, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). - For info about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#same-origin-cors-authentication). + For info about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#same-origin-cors-authentication). ## Additional Information * [Collecting Newsletter Subscriptions](https://support.bigcommerce.com/s/article/Collecting-Newsletter-Subscriptions) (support.bigcommerce.com) - * [Customers Overview](/api-docs/customers/customers-subscribers-overview) - * [Working with Storefront APIs](/api-docs/cart-and-checkout/working-sf-apis) + * [Customers Overview](/docs/store-operations/customers/customers-subscribers-overview) + * [Working with Storefront APIs](/docs/storefront/cart-checkout/guide/rest-storefront) termsOfService: 'https://www.bigcommerce.com/terms' contact: name: BigCommerce diff --git a/reference/tax.v3.yml b/reference/tax.v3.yml index 359cd0dd4..58e9ee964 100644 --- a/reference/tax.v3.yml +++ b/reference/tax.v3.yml @@ -2,7 +2,7 @@ openapi: '3.0.0' info: title: Tax Provider Connection version: '3' - description: 'Manage the connection between a merchantʼs BigCommerce store and a third party tax provider. For more information, see [Tax Provider API Overview](/api-docs/providers/tax).' + description: 'Manage the connection between a merchantʼs BigCommerce store and a third party tax provider. For more information, see [Tax Provider API Overview](/docs/integrations/tax).' termsOfService: 'https://www.bigcommerce.com/terms' contact: name: BigCommerce @@ -49,11 +49,11 @@ paths: delete: summary: Delete a Connection description: | - Remove any previously set basic connection credentials for the specified provider. If the specified provider is the active tax provider on the store, the store's active tax provider will be reset to BigCommerce Manual Tax. It is suggested to call this endpoint during a single-click app [uninstall callback](/api-docs/apps/guide/callbacks#uninstall-callback). + Remove any previously set basic connection credentials for the specified provider. If the specified provider is the active tax provider on the store, the store's active tax provider will be reset to BigCommerce Manual Tax. It is suggested to call this endpoint during a single-click app [uninstall callback](/docs/integrations/apps/guide/callbacks#uninstall-callback). > #### Note > * This operation will be logged in [Store Logs](https://support.bigcommerce.com/s/article/Using-Store-Logs) under **Staff Actions**. - > * Requires **write** permissions on the **Information and Settings** [scope](/api-docs/getting-started/api-accounts#oauth-scopes). + > * Requires **write** permissions on the **Information and Settings** [scope](/docs/start/authentication/api-accounts#oauth-scopes). operationId: provider-connection-delete responses: '200': @@ -69,7 +69,7 @@ paths: username: MyDisconnectedTaxProviderAccount configured: false '404': - description: Provider does not exist + description: Provider or provider connection does not exist tags: - Tax Provider Connection put: @@ -91,11 +91,16 @@ paths: '422': description: 'Unprocessable Entity, will include a specific error message referencing the issue.' description: |- - Set the HTTP Basic Authentication credentials for the specified provider. The configured `username` and `password` will be used to authenticate each API request to the Tax Provider from the associated store. + Set authentication information associated with a merchant's account on the tax provider's infrastructure: + - [HTTP Basic Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication) (developer.mozilla.org) credentials + - (optional) Tax provider profile used in customized endpoint urls for tax provider calls. This is only available for tax providers that support this feature. + + The configured `username`, `password`, and `profile` (if available) is used to authenticate each API request to the Tax Provider from the associated store. + The tax provider's `profile` will be included in the url for [Tax Provider API](/docs/rest-contracts/tax) endpoints. > #### Note > * This operation will be logged in [Store Logs](https://support.bigcommerce.com/s/article/Using-Store-Logs) under **Staff Actions**. - > * Requires **write** permissions on the **Information and Settings** [scope](/api-docs/getting-started/api-accounts#oauth-scopes). + > * Requires **write** permissions on the **Information and Settings** [scope](/docs/start/authentication/api-accounts#oauth-scopes). summary: Update a Connection parameters: - $ref: '#/components/parameters/ContentType' @@ -115,11 +120,16 @@ paths: password: type: string example: h6eSgKLN72q7jYTW + profile: + type: string + example: your_app_name + description: Optional field that allows merchants to customize Tax Provider API endpoint URLs. Only available for supporting providers. examples: Example: value: username: MyTaxProviderAccount password: h6eSgKLN72q7jYTW + profile: test-profile description: Basic authentication information, associated with a merchant account on the third-party tax providerʼs infrastructure. parameters: - $ref: '#/components/parameters/Accept' @@ -128,7 +138,7 @@ paths: required: true schema: type: string - description: 'The Tax Providerʼs `provider_id` provided by BigCommerce after the provider [shares their provider details](/api-docs/providers/tax#sharing-provider-details-with-bigcommerce).' + description: 'The Tax Providerʼs `provider_id` provided by BigCommerce after the provider [shares their provider details](/docs/integrations/tax#sharing-provider-details-with-bigcommerce).' components: parameters: Accept: @@ -169,15 +179,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header schemas: diff --git a/reference/tax_classes.v2.yml b/reference/tax_classes.v2.yml index cc42d906e..cb821f28e 100644 --- a/reference/tax_classes.v2.yml +++ b/reference/tax_classes.v2.yml @@ -174,15 +174,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header diff --git a/reference/tax_properties.v3.yml b/reference/tax_properties.v3.yml index a2bff3fd8..e0c292f0c 100644 --- a/reference/tax_properties.v3.yml +++ b/reference/tax_properties.v3.yml @@ -269,15 +269,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header schemas: diff --git a/reference/tax_provider.yml b/reference/tax_provider.yml index 9380c816d..5856f225e 100644 --- a/reference/tax_provider.yml +++ b/reference/tax_provider.yml @@ -2,7 +2,7 @@ openapi: '3.0.3' info: title: Tax Provider API version: '1.0' - description: 'Use BigCommerce’s platform-to-platform Tax Provider API to integrate a tax calculation engine into the BigCommerce storefront and control panel. Supports [estimate](/docs/apps-api/tax#estimate-taxes), [adjust](/docs/apps-api/tax#adjust-tax-quote), [commit](/docs/apps-api/tax#commit-tax-quote), and [void](/docs/apps-api/tax#void-tax-quote) operations. For more information, see [Tax Provider API Overview](/api-docs/providers/tax).' + description: 'Use BigCommerce’s platform-to-platform Tax Provider API to integrate a tax calculation engine into the BigCommerce storefront and control panel. Supports [estimate](/docs/rest-contracts/tax#estimate-taxes), [adjust](/docs/rest-contracts/tax#adjust-tax-quote), [commit](/docs/rest-contracts/tax#commit-tax-quote), and [void](/docs/rest-contracts/tax#void-tax-quote) operations. For more information, see [Tax Provider API Overview](/docs/integrations/tax).' termsOfService: 'https://www.bigcommerce.com/terms' contact: name: BigCommerce @@ -25,6 +25,10 @@ paths: description: |- Submit the quote request to retrieve an estimate from the enabled third-party tax provider. Estimates are not expected to be persisted by the tax provider. + > Server URL + > - For supporting tax providers, the server URL contains the tax provider's profile field; for example, `your_profile.example.com`. + > - The Try it feature is not currently supported for this endpoint. + The following actions can trigger tax estimate requests multiple times during a standard checkout on a BigCommerce storefront, depending on the BigCommerce merchant’s settings. - After selecting a Shipping Method during the “Estimate Shipping & Tax” facility on the Cart page. @@ -305,7 +309,13 @@ paths: /void: post: summary: Void Tax Quote - description: Invalidate the persisted tax quote as identified by the given unique ID. Relevant to order cancellations or when moving an order from a paid status to an unpaid status. + description: |- + Invalidate the persisted tax quote as identified by the given unique ID. Relevant to order cancellations or when moving an order from a paid status to an unpaid status. + + > Server URL + > - For supporting tax providers, the server URL contains the tax provider's profile field; for example, `your_profile.example.com`. + > - The Try it feature is not currently supported for this endpoint. + operationId: void parameters: - name: id @@ -329,7 +339,13 @@ paths: /commit: post: summary: Commit Tax Quote - description: 'Submit the quote request to be persisted by the enabled third-party tax provider. A commit operation is intended to be submitted once only, when the Order has been confirmed and paid.' + description: |- + Submit the quote request to be persisted by the enabled third-party tax provider. A commit operation is intended to be submitted once only, when the Order has been confirmed and paid. + + > Server URL + > - For supporting tax providers, the server URL contains the tax provider's profile field; for example, `your_profile.example.com`. + > - The Try it feature is not currently supported for this endpoint. + operationId: commit parameters: - $ref: '#/components/parameters/header-storehash' @@ -659,7 +675,7 @@ paths: class_id: string name: string tax_exempt: false - type: item + type: shipping handling: id: string item_code: Flat Rate @@ -674,7 +690,7 @@ paths: class_id: string name: string tax_exempt: false - type: item + type: handling items: - id: string item_code: Flat Rate @@ -704,7 +720,7 @@ paths: class_id: string name: string tax_exempt: false - type: item + type: wrapping '400': description: General response that points to an issue with the incoming request that means a valid response is unable to be returned. '401': @@ -830,6 +846,11 @@ paths: Relevant for partial refunds, full refunds, returns, and other Order modifications where there have been changes to the tax liabilities. The returned **Tax Quote** response is expected to be the same to a response returned by an equivalent response to **estimate** or **commit** methods. + + > Server URL + > - For supporting tax providers, the server URL contains the tax provider's profile field; for example, `your_profile.example.com`. + > - The Try it feature is not currently supported for this endpoint. + operationId: adjust tags: - Tax Provider @@ -883,7 +904,7 @@ components: properties: amount: type: number - description: 'Note: This amount will be **negative** for order-level refunds and may be **zero** for line-item refunds.' + description: 'Note: This amount will be **negative** for order-level refunds and may be **zero** for line item refunds.' format: double example: 1.5 tax_inclusive: @@ -904,94 +925,10 @@ components: description: Merchants may opt to include additional properties that a tax provider can choose to support, factoring these values into tax calculation. items: $ref: '#/components/schemas/request-item-tax-property' - type: - type: string - description: |- - The type of line item this request represents. This will depend on the item’s position in the request hierarchy. For example, the document request contains a collection of items (which may or may not also have wrapping attached). In addition, each document request also has a shipping line item and handling line item. - - The type refund is used when the tax estimate request is for an order-level refund. - enum: - - item - - wrapping - - handling - - shipping - - refund - required: - - id - - price - - quantity - - type - request-item-wrapping: - type: object - description: 'An **ItemRequestWrapping** represents required information relating to completing tax calculations for a specific line item, including the information used to calculate wrapping tax.' - title: ItemRequestWrapping - properties: - id: - type: string - description: A unique identifier for this item used to map responses back to the corresponding item on the order. - item_code: - type: string - description: 'The UPC or SKU of the item. The UPC is used when both UPC and SKU values are available on the item. Empty string if both UPC and SKU are not available.' - item_reference: - type: string - description: 'The SKU of the item. Empty string if SKU is not available.' - name: - type: string - description: A display name for this item. - price: - type: object - description: 'The final sale price (after discounts, bulk pricing, price lists, etc.) prior to having taxes calculated. If the merchant lists prices inclusive of tax, this price will already be tax inclusive, and so the tax provider will instead calculate the amount of tax that was already included in this price. For multiple quantities, this price includes that multiplication.' - required: - - amount - - tax_inclusive - properties: - amount: - type: number - description: 'Note: This amount will be **negative** for order-level refunds and may be **zero** for line-item refunds.' - format: double - tax_inclusive: - type: boolean - description: 'Note: **Tax Inclusive** and **Tax Exclusive** prices cannot be added together.' - default: false - quantity: - type: integer - minimum: 0 - tax_class: - $ref: '#/components/schemas/TaxClass' - tax_exempt: - type: boolean - description: 'Flag whether or not this item is always tax-exempt. For example, gift certificate purchases and order-level refunds are tax-exempt. Tax-exempt items are included in the request for auditing purposes.' - default: false - tax_properties: - type: array - description: Merchants may opt to include additional properties that a tax provider can choose to support, factoring these values into tax calculation. - items: - $ref: '#/components/schemas/request-item-tax-property' - type: - type: string - description: |- - The type of line item this request represents. This will depend on the item’s position in the request hierarchy. For example, the document request contains a collection of items (which may or may not also have wrapping attached). In addition, each document request also has a shipping line item and handling line item. - - The type refund is used when the tax estimate request is for an order-level refund. - enum: - - item - - wrapping - - handling - - shipping - - refund - wrapping: - anyOf: - - $ref: '#/components/schemas/request-item' - - type: object - nullable: true - enum: - - null required: - id - price - quantity - - type - x-internal: false request-item-tax-property: type: object description: A simple key value pairing allowing merchants to provide an additional input into a tax providerʼs tax calculation. @@ -1011,7 +948,7 @@ components: x-internal: false request-document: type: object - description: 'Each **DocumentRequest** represents an order or part of an order of items fulfilled from a single origin address to a single destination address. In addition to shipping and billing details, it contains an `items` array of one or more **ItemRequest** objects, which represent the shipment’s tax-relevant contents. Multi-address orders, in which items ship to or from multiple addresses, require at least one **DocumentRequest** per combination of sender-recipient addresses. These are similar to "consignments" or "shipments" in other BigCommerce APIs.' + description: 'Each **DocumentRequest** represents an order or part of an order of items fulfilled from a single origin address to a single destination address. In addition to shipping and billing details, a document request includes the collection of items in the shipment, with tax-relevant information for each item. Multi-address orders, in which items ship to or from multiple addresses, require at least one **DocumentRequest** per combination of sender-recipient addresses. These are similar to "consignments" or "shipments" in other BigCommerce APIs.' title: DocumentRequest properties: id: @@ -1024,14 +961,51 @@ components: origin_address: $ref: '#/components/schemas/Address' shipping: - $ref: '#/components/schemas/request-item' + type: object + description: Shipping line item present in each document request. + allOf: + - $ref: '#/components/schemas/request-item' + - type: object + properties: + type: + $ref: '#/components/schemas/shipping_type' + required: + - type handling: - $ref: '#/components/schemas/request-item' + type: object + description: Handling line item present in each document request. + allOf: + - $ref: '#/components/schemas/request-item' + - type: object + properties: + type: + $ref: '#/components/schemas/handling_type' + required: + - type items: type: array - description: Collection of one or more items contained within this consignment that need to be assessed for tax liabilities. + description: Collection of one or more items contained within this consignment that need to be assessed for tax liabilities. An item may or may not have gift wrapping. items: - $ref: '#/components/schemas/request-item-wrapping' + allOf: + - $ref: '#/components/schemas/request-item' + - type: object + properties: + type: + $ref: '#/components/schemas/item_type' + wrapping: + type: object + description: Optional gift wrapping for items in the consignment. + nullable: true + allOf: + - $ref: '#/components/schemas/request-item' + - type: object + properties: + type: + $ref: '#/components/schemas/wrapping_type' + required: + - type + required: + - type required: - id - destination_address @@ -1184,13 +1158,50 @@ components: description: 'An optional unique identifier for the document stored in the external provider’s system. Currently not used in any end-to-end operation, but may be logged by BigCommerce and thus be helpful when resolving issues.' items: type: array - description: Collection of items contained within this consignment that have had tax liabilities calculated. + description: Collection of items contained within this consignment that have had tax liabilities calculated. An item may or may not have gift wrapping. items: - $ref: '#/components/schemas/response-item-wrapping' + allOf: + - $ref: '#/components/schemas/response-item' + - type: object + properties: + type: + $ref: '#/components/schemas/item_type' + wrapping: + type: object + description: Optional gift wrapping for items in the consignment. + nullable: true + allOf: + - $ref: '#/components/schemas/response-item' + - type: object + properties: + type: + $ref: '#/components/schemas/wrapping_type' + required: + - type + required: + - type shipping: - $ref: '#/components/schemas/response-item' + type: object + description: Shipping line item present in each document request. + allOf: + - $ref: '#/components/schemas/response-item' + - type: object + properties: + type: + $ref: '#/components/schemas/shipping_type' + required: + - type handling: - $ref: '#/components/schemas/response-item' + type: object + description: Handling line item present in each document request. + allOf: + - $ref: '#/components/schemas/response-item' + - type: object + properties: + type: + $ref: '#/components/schemas/handling_type' + required: + - type required: - id - items @@ -1210,46 +1221,9 @@ components: description: A unique identifier for the line item these tax liabilities are calculated for. Must match the corresponding request line item ID. price: $ref: '#/components/schemas/response-taxprice' - type: - type: string - enum: - - item - - wrapping - - shipping - - handling - - refund required: - id - price - - type - x-internal: false - response-item-wrapping: - type: object - description: |- - The tax liabilities calculated for a specific item, including the liabilities for wrapping tax. - - Note: Tax liabilities should be calculated with **quantity** accounted for. - title: ItemWrapping - properties: - id: - type: string - description: A unique identifier for the line item these tax liabilities are calculated for. Must match the corresponding request line item ID. - price: - $ref: '#/components/schemas/response-taxprice' - type: - type: string - enum: - - item - - wrapping - - shipping - - handling - - refund - wrapping: - $ref: '#/components/schemas/response-item' - required: - - id - - price - - type x-internal: false response-taxprice: type: object @@ -1311,13 +1285,41 @@ components: - rate - amount x-internal: false + item_type: + type: string + description: |- + The type of item for the line item in the document. + + Tax estimate requests for order-level refunds have an additional line item with the type `refund`. + enum: + - item + - refund + shipping_type: + type: string + description: |- + The type of item for the line item in the document. + enum: + - shipping + handling_type: + type: string + description: |- + The type of item for the line item in the document. + enum: + - handling + wrapping_type: + type: string + description: |- + The type of item for the line item in the document. + enum: + - wrapping securitySchemes: Authorization: type: http scheme: basic description: |- - The [HTTP Basic Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication) (developer.mozilla.org) credentials used to authenticate each API request to the Tax Provider from the associated store; set and update `username` and `password` using the [Update a Connection](/docs/apps-api/tax-app-connection#update-a-connection) request. + The [HTTP Basic Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication) (developer.mozilla.org) credentials used to authenticate each API request to the Tax Provider from the associated store; set and update `username`, `password`, and optionally `profile`, using the [Update a Connection](/docs/rest-contracts/tax-app-connection#update-a-connection) request. `profile` is an optional field and will be used with supporting providers only. - For more, see [developer-configured authentication](/api-docs/getting-started/authentication#developer-configured-authentication) for Provider APIs. + For more, see [developer-configured authentication](/docs/start/authentication#developer-configured-authentication) for Provider APIs. + security: - Authorization: [] diff --git a/reference/tax_rates_zones.v3.yml b/reference/tax_rates_zones.v3.yml index 1064667aa..ffbb892a5 100644 --- a/reference/tax_rates_zones.v3.yml +++ b/reference/tax_rates_zones.v3.yml @@ -127,6 +127,7 @@ paths: > #### Note > You cannot create a default tax zone. + operationId: create-tax-zones requestBody: $ref: '#/components/requestBodies/Tax_ZoneArrayPOST' @@ -415,15 +416,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). schemas: Tax_Zone: type: object diff --git a/reference/tax_settings.v3.yml b/reference/tax_settings.v3.yml index 4f65e11ee..bf2e88bf0 100644 --- a/reference/tax_settings.v3.yml +++ b/reference/tax_settings.v3.yml @@ -31,7 +31,7 @@ paths: '200': description: OK content: - application/json: + application/json: schema: type: object properties: @@ -51,7 +51,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/Tax_Settings_Req' + $ref: '#/components/schemas/Tax_Settings' required: true responses: '200': @@ -102,15 +102,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header schemas: @@ -143,33 +143,22 @@ components: - FIXED - BASIC - DISABLE - Tax_Settings_Req: - type: object - properties: - tax_entered_with_prices: + should_subtract_store_tax: + default: true type: boolean - description: Whether prices entered on this store include a tax component or not. - price_display_settings: - type: object - description: Settings that describe how prices display at the global level. - properties: - show_inclusive_in_control_panel: - type: boolean - description: Whether to show prices as tax inclusive or tax exclusive in the BigCommerce control panel. - invoice_price_display_strategy: - type: string - description: 'Whether to show prices as tax inclusive or tax exclusive across all invoices, or use the shopperʼs tax zone for price display on invoices.' - enum: - - ZONE - - INCLUSIVE - - EXCLUSIVE - fallback_strategy: - type: string - description: 'Decribes the fallback behaviour that applies when a tax provider produces an error. A merchant may decide to use a flat 10% fallback tax rate, their basic tax settings, or to block the transaction until a successful result can be achieved.' - enum: - - FIXED - - BASIC - - DISABLE + description: This setting applies only if a merchant enters tax-inclusive prices. When enabled, the store subtracts the itemʼs store tax rate before calculating tax using the shopperʼs tax zone. The tax-exclusive amount will be the same across all tax zones. When disabled, the tax-inclusive price remains the same across all tax zones; only the tax amount will vary based on the shopperʼs location. The tax-exclusive amount may vary among tax zones. These calculations are relevant for tax pricing and tax quotations that use basic tax. + should_use_geolocation_to_determine_guest_shopper_tax_zone: + default: false + type: boolean + description: This setting determines which tax zone a store uses to estimate tax for guest shoppers. When enabled, the store identifies a country-level tax zone based on the geolocation of a guest shopper. The store then applies the corresponding tax zone to estimate taxes. When disabled, the store identifies the zone using the provided `guest_shopper_tax_zone_id` field instead. Only the tax zones you configure can be matched to the guest shopper's geolocation. + guest_shopper_tax_zone_id: + default: 1 + type: integer + description: ID for the tax zone a store uses when estimating tax for guest shoppers. The store uses this zone if you disable `should_use_geolocation_to_determine_guest_shopper_tax_zone`. The store also uses this zone if there is no matching country-level tax zone for the geolocation. + store_tax_zone_id: + default: 1 + type: integer + description: ID for the tax zone a store uses when subtracting store tax. This setting applies only if a merchant enters tax-inclusive prices and subtracts store tax before tax calculation. MetaOpen: title: Response meta type: object diff --git a/reference/themes.v3.yml b/reference/themes.v3.yml index 4f976d0ce..fdb47f8c9 100644 --- a/reference/themes.v3.yml +++ b/reference/themes.v3.yml @@ -465,7 +465,7 @@ paths: additionalProperties: true title: Detailed Errors title: Error Response - description: 'Returns a theme *Job*. If job is completed, the result is included in the response.' + description: 'Returns a theme *Job*. When the job is complete, the results array provides a generated link to access the theme. The link is active for 60 seconds.' parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/JobIdParam' @@ -507,11 +507,6 @@ paths: description: Filter configurations by a variation_uuid. parameters: - $ref: '#/components/parameters/Accept' - - schema: - type: string - name: uuid - in: path - required: true - in: query name: 'site_id:in' description: Filter configurations by a list of site_ids @@ -699,7 +694,7 @@ components: items: $ref: '#/components/schemas/themeConfiguration_Full' meta: - $ref: '#/components/schemas/CollectionMeta' + $ref: '#/components/schemas/ThemesCollectionMeta' examples: response: value: @@ -717,10 +712,6 @@ components: per_page: 50 current_page: 1 total_pages: 1 - links: - previous: nostrud in - current: '?page=1&limit=50' - next: in securitySchemes: X-Auth-Token: name: X-Auth-Token @@ -735,15 +726,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header schemas: @@ -801,6 +792,42 @@ components: Link to the next page returned in the response. title: Collection Meta x-internal: false + ThemesCollectionMeta: + type: object + description: 'Data about the response, including pagination and collection totals.' + properties: + pagination: + type: object + description: 'Data about the response, including pagination and collection totals.' + title: Pagination + properties: + total: + type: integer + description: | + Total number of items in the result set. + example: 36 + count: + type: integer + description: | + Total number of items in the collection response. + example: 36 + per_page: + type: integer + description: | + The amount of items returned in the collection per page, controlled by the limit parameter. + example: 50 + current_page: + type: integer + description: | + The page you are currently on within the collection. + example: 1 + total_pages: + type: integer + description: | + The total number of pages in the collection. + example: 1 + title: Themes Collection Meta + x-internal: false Pagination: type: object description: 'Data about the response, including pagination and collection totals.' diff --git a/reference/webhooks.v3.yml b/reference/webhooks.v3.yml index 1a41ab808..593c19624 100644 --- a/reference/webhooks.v3.yml +++ b/reference/webhooks.v3.yml @@ -2,7 +2,7 @@ openapi: '3.0.3' info: title: Webhooks v3 version: '' - description: 'Get notified when specific events occur on a BigCommerce store. For more information, see [Webhooks Overview](/api-docs/store-management/webhooks/overview).' + description: 'Get notified when specific events occur on a BigCommerce store. For more information, see the [Webhooks Overview](/docs/integrations/webhooks).' termsOfService: 'https://www.bigcommerce.com/terms' contact: email: support@bigcommerce.com @@ -53,7 +53,7 @@ paths: destination: 'https://665b65a6.ngrok.io/webhooks' is_active: true headers: - custom: string + 'custom-key': developer-defined value meta: pagination: count: 5 @@ -164,7 +164,7 @@ paths: '200': $ref: '#/components/responses/webhook_Resp' summary: Delete a Webhook - description: 'Deletes a webhook. Only one webhook at a time can be deleted. When a webhook is deleted, it is returned in the response as a 200 OK.' + description: Deletes a webhook. Only one webhook at a time can be deleted. When a webhook is deleted, it is returned in the response as a 200 OK. operationId: deleteAWebhook tags: - Manage Webhooks (Single) @@ -175,7 +175,7 @@ paths: get: operationId: getHooksAdmin summary: Get Admin Info - description: 'List all notification emails, webhooks, and denylisted domains associated with the API account.' + description: List all notification emails, webhooks, and denylisted domains associated with the API account. parameters: - $ref: '#/components/parameters/IsActive' responses: @@ -197,7 +197,7 @@ paths: format: email example: 'webhooks@example.com' hooks_list: - description: 'List of all the webhooks associated with the provider API account, filtered by the "active" parameter.' + description: 'List of all the webhooks associated with the provider API account, filtered by the `active` parameter.' type: array items: type: object @@ -208,7 +208,7 @@ paths: client_id: type: string minLength: 1 - description: 'Client ID, unique to the store or app.' + description: Client ID, unique to the store or app. store_hash: minLength: 1 type: string @@ -221,13 +221,17 @@ paths: destination: type: string minLength: 1 - description: 'URL must be active, return a 200 response, and be served on port 443 (custom ports not currently supported)' + description: URL must be active, return a 200 response, and be served on port 443. Custom ports arenʼt currently supported. headers: type: object description: You can pass in any number of custom headers to validate webhooks being returned. + properties: {} + nullable: true + additionalProperties: + type: string is_active: type: boolean - description: If webhook is active or not + description: If the webhook is active or not. A webhook subscription becomes deactivated after 90 days of inactivity. default: true created_at: type: integer @@ -235,6 +239,13 @@ paths: updated_at: type: integer description: Updated time + status: + type: string + description: The webhook status. + enum: + - inactive + - active + - deactivated blocked_domains: description: List of domains (destinations) that are currently on the denylist and are not being sent webhooks. type: array @@ -313,6 +324,7 @@ paths: tags: - Webhook Events summary: Get Events + deprecated: true parameters: - $ref: '#/components/parameters/FilterPageParam' - $ref: '#/components/parameters/FilterLimitParam' @@ -357,7 +369,7 @@ components: name: is_active in: query description: | - Enables user to filter for webhooks that are active or not. + Enables user to filter for webhooks that are active or not. A webhook subscription becomes deactivated after 90 days of inactivity. schema: type: boolean example: true @@ -452,7 +464,10 @@ components: minLength: 1 headers: type: object + properties: {} nullable: true + additionalProperties: + type: string is_active: type: boolean created_at: @@ -466,7 +481,7 @@ components: $ref: '#/components/schemas/Pagination' examples: {} 502_GatewayError: - description: 'If something happens during the request that causes it to fail, a 502 response will be returned. A new request should be made; however, it could fail.' + description: If something happens during the request that causes it to fail, a 502 response will be returned. A new request should be made; however, it could fail. content: application/json: schema: @@ -540,7 +555,7 @@ components: title: Unauthorized Access. You do not have permission to make this request. type: /api-docs/getting-started/api-status-codes 404_NotFound: - description: 'If the requested webhook is not found, return a 404 Not Found.' + description: If the requested webhook is not found, return a 404 Not Found. content: application/json: schema: @@ -603,7 +618,12 @@ components: destination: type: string minLength: 1 - headers: {} + headers: + type: object + properties: {} + nullable: true + additionalProperties: + type: string is_active: type: boolean created_at: @@ -628,7 +648,7 @@ components: destination: 'https://665b65a6.ngrok.io/webhooks' is_active: true headers: - custom: string + 'custom-key': developer-defined value meta: pagination: count: 5 @@ -652,21 +672,21 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header schemas: store_cart_wildcard: description: |- - Subscribes to the following events: + Fires for each of the following events: * `store/cart/created` * `store/cart/updated` * `store/cart/deleted` @@ -683,11 +703,12 @@ components: description: |- This webhook fires on new cart creation when any of the following occur: * a storefront shopper adds their first product to a cart during a new session - * thereʼs a successful `POST` request to `/carts` using either the [Storefront](/docs/rest-storefront/carts#create-a-cart) API or the [Store Management](/docs/rest-management/carts/carts-single#create-a-cart) API + * an application makes a successful `POST` request to `/carts` using either the [REST Storefront](/docs/rest-storefront/carts#create-a-cart) API or the [REST Management](/docs/rest-management/carts/carts-single#create-a-cart) API + * a storefront makes a successful call to create a cart using the [GraphQL Storefront API](/docs/storefront/cart-checkout/guide/graphql-storefront) Cart creation also fires the `store/cart/updated` webhook. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -729,7 +750,7 @@ components: store_cart_updated: title: store/cart/updated description: |- - This webhook fires when one of the following occurs: + Fires when one of the following occurs: * A cartʼs line items are modified by adding a new item to a cart, updating an existing itemʼs quantity, or deleting an item. * A shopper enters or changes their email address during guest checkout. This includes signing in to a customer account after creating a guest cart, which associates the accountʼs email address with the cart. @@ -739,7 +760,7 @@ components: * Quantity * Item Price - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -777,10 +798,10 @@ components: store_cart_deleted: title: store/cart/deleted description: |- - This webhook fires whenever a cart is deleted. Carts are deleted in two ways; when all items are removed from a cart, and when an API consumer explicitly removes the cart using a `DELETE` request. Cart deletion ends the cart lifecycle. The `store/cart/updated` webhook also fires when the last item is removed. + Fires when a cart is deleted. Carts are deleted in two ways; when all items are removed from a cart, and when an API consumer explicitly removes the cart using a `DELETE` request. Cart deletion ends the cart lifecycle. The `store/cart/updated` webhook also fires when the last item is removed. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -818,9 +839,9 @@ components: store_cart_couponApplied: title: store/cart/couponApplied description: |- - This webhook fires whenever a new coupon code is applied to a cart. The webhook request body includes the ID of the coupon code. + Fires when a new coupon code is applied to a cart. The webhook request body includes the ID of the coupon code. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -866,7 +887,7 @@ components: This webhook fires after a cart is abandoned. BigCommerce considers a cart abandoned when it has no activity for at least one hour. This webhook is available for all store plans, regardless of whether the Abandoned Cart Saver feature is enabled. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -907,10 +928,10 @@ components: store_cart_converted: title: store/cart/converted description: |- - This webhook fires when a cart/checkout is converted into an order, which is typically after the checkout payment step on the storefront. At this point, the cart is automatically deleted and no longer accessible. This webhook returns both the cart/checkout ID and order ID for correlation purposes. + Fires when a cart/checkout is converted into an order, which is typically after the checkout payment step on the storefront. At this point, the cart is automatically deleted and no longer accessible. This webhook returns both the cart/checkout ID and order ID for correlation purposes. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -955,7 +976,7 @@ components: description: |- This webhook subscribes to all cart line item events. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -994,9 +1015,9 @@ components: store_cart_lineItem_created: title: store/cart/lineItem/created description: |- - This webhook fires when a new item is added to the cart. + Fires when a new item is added to the cart. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -1039,13 +1060,13 @@ components: store_cart_lineItem_updated: title: store/cart/lineItem/updated description: |- - This webhook fires when an item’s quantity has changed or the product options change. + Fires when an item’s quantity has changed or the product options change. Changes to the following fields trigger this event: * Quantity * Item Price - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -1088,9 +1109,9 @@ components: store_cart_lineItem_deleted: title: store/cart/lineItem/deleted description: |- - This webhook fires when an item is deleted from the cart. + Fires when an item is deleted from the cart. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -1133,7 +1154,7 @@ components: store_category_wildcard: title: store/category/* description: | - Subscribe to all store/category events + Fires for all `store/category` events. x-examples: {} allOf: [] x-tags: @@ -1143,9 +1164,9 @@ components: title: store/category/created type: object description: |- - This webhook fires when a category is created. + Fires when a category is created. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -1169,7 +1190,7 @@ components: store_category_updated: title: store/category/updated description: |- - This webhook fires when a category is updated. + Fires when a category is updated. Changes to the following fields trigger this event: * URL @@ -1189,7 +1210,7 @@ components: * Enable Google Shopping - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -1226,9 +1247,9 @@ components: store_category_deleted: title: store/category/deleted description: |- - This webhook fires when a category is deleted. + Fires when a category is deleted. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -1265,7 +1286,7 @@ components: x-internal: false store_channel_wildcard: title: store/channel/* - description: 'Subscribe to all `store/channel` events. ' + description: Fires for all `store/channel` events. allOf: [] x-tags: - created @@ -1273,9 +1294,9 @@ components: store_channel_created: title: store/channel/created description: |- - This webhook fires when a channel is created in the control panel or by API. + Fires when a channel is created in the control panel or by API. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -1326,7 +1347,7 @@ components: * config_meta - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -1366,7 +1387,7 @@ components: store_customer_wildcard: title: store/customer/* description: | - Subscribe to all `store/customer` events + Fires for all `store/customer` events. x-examples: {} allOf: [] x-tags: @@ -1375,9 +1396,9 @@ components: store_customer_created: title: store/customer/created description: |- - This webhook fires when a new customer is created. + Fires when a new customer is created. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -1420,7 +1441,7 @@ components: This webhook is triggered when a customer is updated. In addition, this webhook is triggered when a shopper initially enters custom form field values within the account sign-up form. Please note that neither changing existing data in customer form fields nor changing a customerʼs address will trigger the webhook. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -1462,7 +1483,7 @@ components: description: |- This webhook is triggered when a customer is deleted. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -1501,9 +1522,9 @@ components: store_customer_address_updated: title: store/customer/address/updated description: |- - This webhook fires when a customer address is updated. + Fires when a customer address is updated. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -1551,9 +1572,9 @@ components: store_customer_address_created: title: store/customer/address/created description: |- - This webhook fires when a customer address is created. + Fires when a customer address is created. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -1601,9 +1622,9 @@ components: store_customer_address_deleted: title: store/customer/address/deleted description: |- - This webhook fires when a customer address is deleted. + Fires when a customer address is deleted. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -1651,9 +1672,9 @@ components: store_customer_payment_instrument_default_updated: title: store/customer/payment/instrument/default/updated description: |- - This webhook fires when a customer default payment instrument is updated. + Fires when a customer default payment instrument is updated. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -1691,7 +1712,7 @@ components: x-internal: false store_order_wildcard: title: store/order/* - description: Subscribe to all store/order events. + description: Fires for all `store/order` events. type: object x-internal: false store_order_created: @@ -1699,7 +1720,7 @@ components: description: |- This webhook is triggered when an order is created in the control panel, using an app, or by API. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -1738,7 +1759,7 @@ components: store_order_updated: title: store/order/updated description: |- - This webhook fires when a previously-created order is updated. + Fires when a previously-created order is updated. Changes to the following fields trigger this event: * Status @@ -1760,7 +1781,7 @@ components: * Release Date * Remove pre-order status on this date - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -1799,9 +1820,9 @@ components: store_order_archived: title: store/order/archived description: |- - This webhook fires when an order is archived. + Fires when an order is archived. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -1841,7 +1862,7 @@ components: description: |- This webhook is triggered when an order status changes; for example, from `Pending` to `Awaiting Payment`. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -1896,7 +1917,7 @@ components: description: |- This webhook is triggered when an order message is created by a customer or in the control panel. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -1946,7 +1967,7 @@ components: description: |- This webhook is triggered when a refund is submitted against an order. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -1993,7 +2014,7 @@ components: x-internal: false store_product_wildcard: title: store/product/* - description: Subscribe to all `store/product` events. + description: Fires for all `store/product` events. type: object x-internal: false store_product_deleted: @@ -2001,7 +2022,7 @@ components: description: |- This webhook is triggered when a product is deleted. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -2040,9 +2061,9 @@ components: store_product_created: title: store/product/created description: |- - This webhook fires when a new product is created. + Fires when a new product is created. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -2081,7 +2102,7 @@ components: store_product_updated: title: store/product/updated description: |- - This webhook fires when product details are edited. + Fires when product details are edited. Changes to the following fields trigger this event: * Product Type @@ -2125,7 +2146,7 @@ components: * Product URL * Set as a Featured Product on my Storefront - However, changes to the following fields don't trigger this event: + However, changes to the following fields donʼt trigger this event: * Manufacturer Part Number (MPN) * Global Trade Number (GTN) @@ -2135,7 +2156,7 @@ components: * Product Files * Customs Information - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -2179,12 +2200,12 @@ components: Changes to the following fields trigger this event: * Inventory Stock - However, changes to the following fields don't trigger this event: + However, changes to the following fields donʼt trigger this event: * Track Inventory * Inventory Low Stock - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -2252,7 +2273,7 @@ components: Changes to the following fields trigger this event: * Quantity - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -2314,15 +2335,15 @@ components: x-internal: false store_shipment_wildcard: title: store/shipment/* - description: Subscribe to all store/shipment events + description: Fires for all `store/shipment` events. type: object x-internal: false store_shipment_created: title: store/shipment/created description: |- - This webhook fires when a shipment is created. + Fires when a shipment is created. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -2365,12 +2386,12 @@ components: store_shipment_updated: title: store/shipment/updated description: |- - This webhook fires when a shipment is updated. + Fires when a shipment is updated. Changes to the following fields trigger this event: * Shipping Tracking Number - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -2415,7 +2436,7 @@ components: description: |- This webhook is triggered when a shipment is deleted. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -2457,7 +2478,7 @@ components: x-internal: false store_sku_wildcard: title: store/sku/* - description: Subscribe to all `store/sku` events. + description: Fires for all `store/sku` events. type: object x-internal: false store_sku_created: @@ -2465,7 +2486,7 @@ components: description: |- This webhook is triggered when a new SKU is created. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -2518,9 +2539,9 @@ components: store_sku_updated: title: store/sku/updated description: |- - This webhook fires when a SKU is updated. + Fires when a SKU is updated. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -2573,9 +2594,9 @@ components: store_sku_deleted: title: store/sku/deleted description: |- - This webhook fires when a SKU is deleted. + Fires when a SKU is deleted. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -2628,9 +2649,9 @@ components: store_sku_inventory_updated: title: store/sku/inventory/updated description: |- - This webhook fires when a SKU is updated. + Fires when a SKU is updated. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -2698,12 +2719,12 @@ components: store_sku_inventory_order_updated: title: store/sku/inventory/order/updated description: |- - This webhook fires when the inventory is updated. + Fires when the inventory is updated. Changes to the following fields trigger this event: * Quantity - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -2771,9 +2792,9 @@ components: store_app_uninstalled: title: store/app/uninstalled description: |- - This webhook fires when a client store is canceled and uninstalled from the platform. + Fires when a client store is canceled and uninstalled from the platform. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -2806,7 +2827,7 @@ components: store_information_updated: title: store/information/updated description: |- - This webhook fires when changes are made to store settings. + Fires when changes are made to store settings. Changes to the following fields trigger this event: * Store Name @@ -2816,7 +2837,7 @@ components: * Email * Phone - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -2848,15 +2869,15 @@ components: x-internal: false store_subscriber_wildcard: title: store/subscriber/* - description: Subscribe to all `store/subscriber` events + description: Fires for all `store/subscriber` events. type: object x-internal: false store_subscriber_created: title: store/subscriber/created description: |- - This webhook fires when a subscriber is created. + Fires when a subscriber is created. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -2896,7 +2917,7 @@ components: description: |- The webhook fires when a subscriber is updated. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -2936,7 +2957,7 @@ components: description: |- This webhook is triggered when a subscriber is deleted. - ```json title="Example callback object" lineNumbers + ```json filename="Example callback object" showLineNumbers { "created_at": 1561482670, "store_id": "1025646", @@ -3044,26 +3065,26 @@ components: destination: type: string example: 'https://665b65a6.ngrok.io/webhooks' - description: 'URL must be active, return a 200 response, and be served on port 443 (custom ports not currently supported).' + description: URL must be active, return a 200 response, and be served on port 443. Custom ports arenʼt currently supported. is_active: type: boolean example: true - description: Boolean value that indicates whether the webhook is active or not. + description: Boolean value that indicates whether the webhook is active or not. A webhook subscription becomes deactivated after 90 days of inactivity. events_history_enabled: type: boolean example: true - description: Boolean value that identifies whether events are stored that could not be received. + description: Deprecated. Boolean value that identifies whether events are stored that could not be received. + deprecated: true 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. ' + 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 + properties: {} + additionalProperties: + type: string required: - scope - destination - - headers webhook_Full: allOf: - $ref: '#/components/schemas/webhook_Base' @@ -3075,7 +3096,7 @@ components: example: 18048287 client_id: type: string - description: 'Client ID, unique to the store or app.' + description: Client ID, unique to the store or app. example: m9r6keqmo7h7f23btnpwernbez1kglkl store_hash: type: string diff --git a/reference/widgets.v3.yml b/reference/widgets.v3.yml index 0708de33a..3dc19e234 100644 --- a/reference/widgets.v3.yml +++ b/reference/widgets.v3.yml @@ -8,7 +8,7 @@ info: ## Subresources ### Widget templates - [Widget templates](/rest-content/widgets/widget-template) are reusable Handlebars-enabled HTML templates that define the structure of the widget on a page. + [Widget templates](/docs/rest-content/widgets/widget-template) are reusable Handlebars-enabled HTML templates that define the structure of the widget on a page. ### Widgets [Widgets](/docs/rest-content/widgets/widget) are units of content placed on specific pages in a Stencil theme. Widgets consist of a widget configuration and a widget template UUID and render as part of the storefront’s HTML. @@ -21,9 +21,9 @@ info: ## Additional Information - * [Widgets API Overview](/api-docs/store-management/widgets/overview) - * [Widget UI Schema](/stencil-docs/page-builder/widget-ui-schema) - * [Widget UI Input Types](/stencil-docs/page-builder/schema-settings) + * [Widgets API Overview](/docs/storefront/widgets) + * [Widget UI Schema](/docs/storefront/widgets/input-reference/schema) + * [Widget UI Input Types](/docs/storefront/widgets/input-reference/settings) termsOfService: 'https://www.bigcommerce.com/terms' contact: name: BigCommerce @@ -117,7 +117,7 @@ paths: description: |- Creates a **Widget Template**. - ***Note:*** *There is a limit of 100 custom widget templates per store.* + ***Note:*** *There is a limit of 1000 custom widget templates per store.* **Required Fields** * name @@ -288,7 +288,7 @@ paths: description: |- Creates a **Widget**. - **Note:** There is a limit of 10,000 widgets per store and 150 widgets per page. For more information, see [Store Limits](https://support.bigcommerce.com/s/article/Platform-Limits#storelimits). + **Note:** There is a limit of 100,000 widgets per store and 150 widgets per page. For more information, see [Store Limits](https://support.bigcommerce.com/s/article/Platform-Limits#storelimits). get: tags: - Widget @@ -443,7 +443,7 @@ paths: **Template Files** - To view the list of values accepted by the `template_file` property, including **custom** templates, see [Placements](/api-docs/store-management/widgets/overview#placements). + To view the list of values accepted by the `template_file` property, including **custom** templates, see [Placements](/docs/storefront/widgets#placements). get: tags: - Placement @@ -747,17 +747,17 @@ components: description: The page template name. region: type: string - description: The name of the region defined in the stencil theme file. + description: The name of the region defined in the Stencil theme file. markup: type: string - description: The HTML layout which defines complex poisitoning for placements. + description: The HTML layout which defines complex positioning for placements. date_created: type: string - format: datetime + format: date-time description: The date on which this object was initially created. date_modified: type: string - format: datetime + format: date-time description: The date on which this object was last updated. title: Layout meta: @@ -848,17 +848,17 @@ components: description: The page template name. region: type: string - description: The name of the region defined in the stencil theme file. + description: The name of the region defined in the Stencil theme file. markup: type: string - description: The HTML layout which defines complex poisitoning for placements. + description: The HTML layout which defines complex positioning for placements. date_created: type: string - format: datetime + format: date-time description: The date on which this object was initially created. date_modified: type: string - format: datetime + format: date-time description: The date on which this object was last updated. title: Layout PlacementsCollection_Resp: @@ -1294,15 +1294,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header schemas: @@ -1385,11 +1385,11 @@ components: description: The kind of widget template. date_created: type: string - format: datetime + format: date-time description: The date on which this object was initially created. date_modified: type: string - format: datetime + format: date-time description: The date on which this object was last updated. current_version_uuid: type: string @@ -1415,11 +1415,11 @@ components: $ref: '#/components/schemas/widgetTemplate_Full' date_created: type: string - format: datetime + format: date-time description: The date on which this object was initially created. date_modified: type: string - format: datetime + format: date-time description: The date on which this object was last updated. version_uuid: type: string @@ -1517,11 +1517,11 @@ components: description: The template file that you would like to target. date_created: type: string - format: datetime + format: date-time description: The date on which this object was initially created. date_modified: type: string - format: datetime + format: date-time description: The date on which this object was last updated. channel_id: type: integer @@ -1750,18 +1750,18 @@ components: example: Product settings: type: array - description: 'For examples of schema settings, see [Widget UI Input Types](/stencil-docs/page-builder/schema-settings).' + description: 'For examples of schema settings, see [Widget UI Input Types](/docs/storefront/widgets/input-reference/settings).' items: type: object title: widgetSchemaSetting_Base - description: 'For examples of each type of setting, see [Page Builder > Schema Settings](/stencil-docs/page-builder/schema-settings/alignment) in Theme Docs.' + description: 'For examples of each type of setting, see [Page Builder > Schema Settings](/docs/storefront/widgets/input-reference/settings#alignment) in Theme Docs.' properties: type: type: string description: |- The type of setting component to display. You can view the list of elements below to discover which are available to use. - For examples of each type of setting, see [Page Builder > Schema Settings](/stencil-docs/page-builder/schema-settings/alignment) in Theme Docs. + For examples of each type of setting, see [Page Builder > Schema Settings](/docs/storefront/widgets/input-reference/settings#alignment) in Theme Docs. enum: - alignment - boolean @@ -1835,7 +1835,7 @@ components: type: string settings: type: array - description: 'For examples of each type of setting, see [Page Builder > Schema Settings](/stencil-docs/page-builder/schema-settings/alignment) in Theme Docs.' + description: 'For examples of each type of setting, see [Page Builder > Schema Settings](/docs/storefront/widgets/input-reference/settings#alignment) in Theme Docs.' items: $ref: '#/components/schemas/widgetSchemaSetting_Base' x-internal: false @@ -1879,14 +1879,14 @@ components: widgetSchemaSetting_Base: type: object title: widgetSchemaSetting_Base - description: 'For examples of each type of setting, see [Page Builder > Schema Settings](/stencil-docs/page-builder/schema-settings/alignment) in Theme Docs.' + description: 'For examples of each type of setting, see [Page Builder > Schema Settings](/docs/storefront/widgets/input-reference/settings#alignment) in Theme Docs.' properties: type: type: string description: |- The type of setting component to display. You can view the list of elements below to discover which are available to use. - For examples of each type of setting, see [Page Builder > Schema Settings](/stencil-docs/page-builder/schema-settings/alignment) in Theme Docs. + For examples of each type of setting, see [Page Builder > Schema Settings](/docs/storefront/widgets/input-reference/settings#alignment) in Theme Docs. enum: - alignment - boolean @@ -1932,7 +1932,7 @@ components: x-internal: false widgetSchema: type: array - description: 'The schema for the widget’s merchant-facing UI. For more information on the available schema settings, see [Widget UI Schema](/stencil-docs/page-builder/widget-ui-schema). ' + description: 'The schema for the widget’s merchant-facing UI. For more information on the available schema settings, see [Widget UI Schema](/docs/storefront/widgets/input-reference/schema). ' title: '' items: anyOf: @@ -1956,14 +1956,14 @@ components: items: type: object title: widgetSchemaSetting_Base - description: 'For examples of each type of setting, see [Page Builder > Schema Settings](/stencil-docs/page-builder/schema-settings/alignment) in Theme Docs.' + description: 'For examples of each type of setting, see [Page Builder > Schema Settings](/docs/storefront/widgets/input-reference/settings#alignment) in Theme Docs.' properties: type: type: string description: |- The type of setting component to display. You can view the list of elements below to discover which are available to use. - For examples of each type of setting, see [Page Builder > Schema Settings](/stencil-docs/page-builder/schema-settings/alignment) in Theme Docs. + For examples of each type of setting, see [Page Builder > Schema Settings](/docs/storefront/widgets/input-reference/settings#alignment) in Theme Docs. enum: - alignment - boolean diff --git a/reference/wishlists.v3.yml b/reference/wishlists.v3.yml index 3faa8c029..13988d961 100644 --- a/reference/wishlists.v3.yml +++ b/reference/wishlists.v3.yml @@ -2,10 +2,11 @@ openapi: '3.0.1' info: title: Wishlist description: |- - Create and manage customer [wishlists](https://support.bigcommerce.com/s/article/Wishlists). + Create and manage customer wishlists and wishlist items. ## Additional Information - * [Wishlists](https://support.bigcommerce.com/s/article/Wishlists) + + * [Wishlists (Help Center)](https://support.bigcommerce.com/s/article/Wishlists) version: '' termsOfService: 'https://www.bigcommerce.com/terms' contact: @@ -23,7 +24,6 @@ security: - X-Auth-Token: [] tags: - name: Wishlists - description: '' - name: Wishlists Items paths: '/wishlists': @@ -241,23 +241,22 @@ paths: type: string type: type: string - x-codegen-request-body-name: body '/wishlists/{wishlist_id}/items/{item_id}': + parameters: + - $ref: '#/components/parameters/WishlistID' + - $ref: '#/components/parameters/Accept' + - name: item_id + in: path + required: true + schema: + type: integer + format: int32 delete: tags: - Wishlists Items summary: Delete Wishlist Item description: Deletes a wishlist item. operationId: WishlistsItemsByIdDelete - parameters: - - $ref: '#/components/parameters/WishlistID' - - $ref: '#/components/parameters/Accept' - - name: item_id - in: path - required: true - schema: - type: integer - format: int32 responses: '200': description: '' @@ -334,15 +333,15 @@ paths: type: type: string '/wishlists/{wishlist_id}': + parameters: + - $ref: '#/components/parameters/WishlistID' + - $ref: '#/components/parameters/Accept' get: tags: - Wishlists summary: Get a Wishlist description: Returns a single wishlist. operationId: WishlistsByIdGet - parameters: - - $ref: '#/components/parameters/WishlistID' - - $ref: '#/components/parameters/Accept' responses: '200': description: '' @@ -425,11 +424,9 @@ paths: description: |- Updates a wishlist. - Use this endpoint to update existing wishlist items, change the wishlist's name and whether the wishlist is available publicly. To add or delete a wishlist item, see [Wishlist Items](/docs/rest-management/wishlists/wishlists-items). + Use this endpoint to update existing wishlist items, change the wishlistʼs name and whether the wishlist is available publicly. To add or delete a wishlist item, see [Wishlist Items](/docs/rest-management/wishlists/wishlists-items). operationId: WishlistsByIdPut parameters: - - $ref: '#/components/parameters/WishlistID' - - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/ContentType' requestBody: content: @@ -506,16 +503,12 @@ paths: type: string type: type: string - x-codegen-request-body-name: body delete: tags: - Wishlists summary: Delete a Wishlist description: Deletes a wishlist. operationId: WishlistsByIdDelete - parameters: - - $ref: '#/components/parameters/WishlistID' - - $ref: '#/components/parameters/Accept' responses: '204': description: '' @@ -551,6 +544,9 @@ paths: type: type: string '/wishlists/{wishlist_id}/items': + parameters: + - $ref: '#/components/parameters/WishlistID' + - $ref: '#/components/parameters/Accept' post: tags: - Wishlists Items @@ -558,8 +554,6 @@ paths: description: Adds a wishlist item. More than one item can be added at a time. operationId: WishlistsItemsByIdPost parameters: - - $ref: '#/components/parameters/WishlistID' - - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/ContentType' requestBody: content: @@ -627,7 +621,6 @@ paths: '500': description: Internal server error. content: {} - x-codegen-request-body-name: body components: schemas: wishlist_Post: @@ -806,18 +799,6 @@ components: format: int32 description: 'Data about the response, including pagination and collection totals.' x-internal: false - error: - title: error - type: object - properties: - status: - type: integer - format: int32 - title: - type: string - type: - type: string - x-internal: false metaCollection: title: metaCollection type: object @@ -825,150 +806,7 @@ components: pagination: $ref: '#/components/schemas/pagination' x-internal: false - responses: - Unauthorized: - description: Authentication information is missing or invalid. - content: - application/json: - schema: - title: Error - type: object - properties: - status: - type: integer - format: int32 - title: - type: string - type: - type: string - Wishlist_Resp: - description: '' - content: - application/json: - schema: - type: object - properties: - data: - $ref: '#/components/schemas/wishlist_Full' - meta: - type: object - properties: {} - additionalProperties: true - description: Response metadata. - example: - data: - id: 30 - customer_id: 10 - name: Christmas List - is_public: true - token: d2d55481-13eb-4d1e-9d79-9062b518570d - items: - - id: 44 - product_id: 77 - variant_id: 1 - - id: 45 - product_id: 80 - variant_id: 1 - - id: 46 - product_id: 81 - variant_id: 1 - - id: 47 - product_id: 86 - variant_id: 1 - - id: 48 - product_id: 88 - variant_id: 1 - meta: {} - wishlist_Resp_Collection: - description: '' - content: - application/json: - schema: - type: object - properties: - data: - type: array - items: - $ref: '#/components/schemas/wishlist_Full' - meta: - $ref: '#/components/schemas/metaCollection' - example: - data: - - id: 1 - customer_id: 4 - name: My Wish List - is_public: false - token: 02d55481-13eb-4d1e-9d79-9062b518570d - items: [] - - id: 2 - customer_id: 11 - name: Christmas - is_public: false - token: 02d55481-13eb-4d1e-9d79-9062b518570e - items: - - id: 1 - product_id: 167 - - id: 2 - product_id: 174 - - id: 3 - product_id: 184 - - id: 3 - customer_id: 20 - name: Birthday - is_public: false - token: 02d55481-13eb-4d1e-9d79-9062b518570f - items: - - id: 4 - product_id: 184 - - id: 5 - product_id: 183 - - id: 4 - customer_id: 20 - name: Christmas - is_public: false - token: 02d55481-13eb-4d1e-9d79-9062b518570f - items: - - id: 6 - product_id: 201 - - id: 5 - customer_id: 19 - name: Wish List - is_public: false - token: 02d55481-13eb-4d1e-9d79-9062b518570f - items: - - id: 7 - product_id: 173 - - id: 8 - product_id: 176 - meta: - pagination: - total: 0 - count: 5 - per_page: 50 - current_page: 1 - total_pages: 0 parameters: - FilterCustomerID: - name: customer_id - in: query - description: All wishlists relating to the customer. - schema: - type: integer - format: int32 - FilterPage: - name: page - in: query - description: The page number of results per page. 1 is the default and starts from record 0. - schema: - type: integer - format: int32 - FilterLimit: - name: limit - in: query - description: The numbers of items to return per page. Default is 50 and maximum is 250. - schema: - type: integer - format: int32 WishlistID: name: wishlist_id in: path @@ -1008,15 +846,15 @@ components: | Header | Argument | Description | |:-------|:---------|:------------| - | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts). | + | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading - For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/api-docs/getting-started/authentication#x-auth-token-header-example-requests). + For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). - For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/api-docs/getting-started/api-accounts#oauth-scopes). + For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). - For a list of API status codes, see [API Status Codes](/api-docs/getting-started/api-status-codes). + For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes). type: apiKey in: header diff --git a/toc.json b/toc.json deleted file mode 100644 index 65e4fd0ce..000000000 --- a/toc.json +++ /dev/null @@ -1,320 +0,0 @@ -{ - "items": [ - { - "type": "divider", - "title": "Storefront APIs" - }, - { - "type": "item", - "title": "Carts", - "uri": "reference/carts.sf.yml" - }, - { - "type": "item", - "title": "Checkouts", - "uri": "reference/checkouts.sf.yml" - }, - { - "type": "item", - "title": "Cookie Consent", - "uri": "reference/consent.sf.yml" - }, - { - "type": "item", - "title": "Current Customers", - "uri": "reference/current_customer.yml" - }, - { - "type": "item", - "title": "Customers", - "uri": "reference/customers.sf.yml" - }, - { - "type": "item", - "title": "Customer Login SSO", - "uri": "docs/customer-login-sso.md" - }, - { - "type": "item", - "title": "Customer Login", - "uri": "reference/customer_login.yml" - }, - { - "type": "item", - "title": "Form Fields", - "uri": "reference/form_fields.sf.yml" - }, - { - "type": "item", - "title": "Email Subscriptions", - "uri": "reference/subscriptions.sf.yml" - }, - { - "type": "item", - "title": "Orders", - "uri": "reference/orders.sf.yml" - }, - { - "type": "divider", - "title": "GraphQL" - }, - { - "type": "item", - "title": "GraphQL Storefront API", - "uri": "docs/storefront-graphql.md" - }, - { - "type": "item", - "title": "GraphQL Storefront API Reference", - "uri": "https://developer.bigcommerce.com/graphql-api-reference" - }, - { - "type": "divider", - "title": "Management APIs" - }, - { - "type": "item", - "title": "Abandoned Carts", - "uri": "reference/abandoned_carts.v3.yml" - }, - { - "type": "item", - "title": "Abandoned Cart Emails (Beta)", - "uri": "reference/abandoned_cart_emails.v3.yaml" - }, - { - "type": "item", - "title": "Carts", - "uri": "reference/carts.v3.yml" - }, - { - "type": "item", - "title": "Catalog", - "uri": "reference/catalog.v3.yml" - }, - { - "type": "item", - "title": "Channels", - "uri": "reference/channels.v3.yml" - }, - { - "type": "item", - "title": "Checkouts", - "uri": "reference/checkouts.v3.yml" - }, - { - "type": "item", - "title": "Currencies", - "uri": "reference/currencies.v2.yml" - }, - { - "type": "item", - "title": "Customers v2", - "uri": "reference/customers.v2.yml" - }, - { - "type": "item", - "title": "Customers v3", - "uri": "reference/customers.v3.yml" - }, - { - "type": "item", - "title": "Custom Template Associations", - "uri": "reference/custom-template-associations.v3.yml" - }, - { - "type": "item", - "title": "Email Templates", - "uri": "reference/email_templates.v3.yml" - }, - { - "type": "item", - "title": "Geography", - "uri": "reference/geography.v2.yml" - }, - { - "type": "item", - "title": "GraphQL Tokens", - "uri": "reference/storefront_tokens.v3.yml" - }, - { - "type": "item", - "title": "Marketing", - "uri": "reference/marketing.v2.yml" - }, - { - "type": "item", - "title": "Orders v2", - "uri": "reference/orders.v2.oas2.yml" - }, - { - "type": "item", - "title": "Orders v3", - "uri": "reference/orders.v3.yml" - }, - { - "type": "item", - "title": "Pages v3", - "uri": "reference/pages.v3.yml" - }, - { - "type": "item", - "title": "Payment Methods", - "uri": "reference/payment_methods.v2.yml" - }, - { - "type": "item", - "title": "Payment Processing", - "uri": "reference/payment_processing.yml" - }, - { - "type": "item", - "title": "Pricing", - "uri": "reference/pricing.sf.yml" - }, - { - "type": "item", - "title": "Price Lists", - "uri": "reference/price_lists.v3.yml" - }, - { - "type": "item", - "title": "Redirects v3", - "uri": "reference/redirects.v3.yml" - }, - { - "type": "item", - "title": "Scripts", - "uri": "reference/scripts.v3.yml" - }, - { - "type": "item", - "title": "Settings", - "uri": "reference/settings.v3.yml" - }, - { - "type": "item", - "title": "Shipping v2", - "uri": "reference/shipping.v2.yml" - }, - { - "type": "item", - "title": "Shipping v3", - "uri": "reference/shipping.v3.yml" - }, - { - "type": "item", - "title": "Sites", - "uri": "reference/sites.v3.yml" - }, - { - "type": "item", - "title": "Store Content", - "uri": "reference/store_content.v2.yml" - }, - { - "type": "item", - "title": "Store Information", - "uri": "reference/store_information.v2.yml" - }, - { - "type": "item", - "title": "Store Logs", - "uri": "reference/store_logs.v3.yml" - }, - { - "type": "item", - "title": "Subscribers", - "uri": "reference/subscribers.v3.yml" - }, - { - "type": "item", - "title": "Tax Classes", - "uri": "reference/tax_classes.v2.yml" - }, - { - "type": "item", - "title": "Tax Rates and Zones", - "uri": "reference/tax_rates_zones.v3.yml" - }, - { - "type": "item", - "title": "Tax Properties", - "href": "/api-reference/store-management/tax-properties", - "uri": "reference/tax_properties.v3.yml" - }, - { - "type": "item", - "title": "Tax Provider Connection", - "uri": "reference/tax.v3.yml" - }, - { - "type": "item", - "title": "Tax Settings", - "href": "/api-reference/store-management/tax-settings", - "uri": "reference/tax_settings.v3.yml" - }, - { - "type": "item", - "title": "Themes", - "uri": "reference/themes.v3.yml" - }, - { - "type": "item", - "title": "Webhooks", - "uri": "reference/webhooks.v3.yml" - }, - { - "type": "item", - "title": "Widgets", - "uri": "reference/widgets.v3.yml" - }, - { - "type": "item", - "title": "Wishlists", - "uri": "reference/wishlists.v3.yml" - }, - { - "type": "divider", - "title": "Provider APIs" - }, - { - "type": "item", - "title": "Shipping Provider API", - "uri": "reference/shipping_provider.yml" - }, - { - "type": "item", - "title": "Tax Provider API", - "uri": "reference/tax_provider.yml" - }, - { - "type": "divider", - "title": "Beta APIs" - }, - { - "type": "item", - "title": "Promotions API", - "uri": "https://developer.bigcommerce.com/promotions/beta/api-reference" - }, - { - "type": "item", - "title": "Customer Segmentation API", - "uri": "https://developer.bigcommerce.com/customers/beta/api-reference" - }, - { - "type": "divider", - "title": "Template Objects" - }, - { - "type": "item", - "title": "Handlebars Email Template Objects", - "uri": "models/email_templates/_all.yml" - }, - { - "type": "item", - "title": "Template Object Reference", - "uri": "https://developer.bigcommerce.com/theme-objects" - } - ] -}