{"id":28321809,"url":"https://github.com/ordercloud-api/ordercloud-javascript-sdk","last_synced_at":"2026-04-09T05:32:24.366Z","repository":{"id":37514012,"uuid":"78888564","full_name":"ordercloud-api/ordercloud-javascript-sdk","owner":"ordercloud-api","description":"The official Javascript SDK for the OrderCloud eCommerce platform","archived":false,"fork":false,"pushed_at":"2025-12-17T16:02:12.000Z","size":8780,"stargazers_count":17,"open_issues_count":4,"forks_count":17,"subscribers_count":9,"default_branch":"master","last_synced_at":"2026-02-06T21:45:29.068Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ordercloud-api.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-01-13T21:35:56.000Z","updated_at":"2025-12-17T16:00:51.000Z","dependencies_parsed_at":"2023-07-13T15:33:00.762Z","dependency_job_id":"a6116188-ad5c-4602-adfc-e27564a50752","html_url":"https://github.com/ordercloud-api/ordercloud-javascript-sdk","commit_stats":{"total_commits":263,"total_committers":11,"mean_commits":23.90909090909091,"dds":"0.28136882129277563","last_synced_commit":"1b5c7e002c29d353de26417b7c7954f4928babf2"},"previous_names":["cobrien451/ordercloud-javascript-sdk"],"tags_count":123,"template":false,"template_full_name":null,"purl":"pkg:github/ordercloud-api/ordercloud-javascript-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ordercloud-api%2Fordercloud-javascript-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ordercloud-api%2Fordercloud-javascript-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ordercloud-api%2Fordercloud-javascript-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ordercloud-api%2Fordercloud-javascript-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ordercloud-api","download_url":"https://codeload.github.com/ordercloud-api/ordercloud-javascript-sdk/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ordercloud-api%2Fordercloud-javascript-sdk/sbom","scorecard":{"id":711891,"data":{"date":"2025-08-11","repo":{"name":"github.com/ordercloud-api/ordercloud-javascript-sdk","commit":"d6582c561f5ef5c1743a698748794878e889b21b"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":4.4,"checks":[{"name":"Maintained","score":10,"reason":"30 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 10","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Code-Review","score":1,"reason":"Found 1/8 approved changesets -- score normalized to 1","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/ci.yml:1","Warn: topLevel 'contents' permission set to 'write': .github/workflows/tag-and-publish.yml:4","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:12: update your workflow using https://app.stepsecurity.io/secureworkflow/ordercloud-api/ordercloud-javascript-sdk/ci.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:14: update your workflow using https://app.stepsecurity.io/secureworkflow/ordercloud-api/ordercloud-javascript-sdk/ci.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/tag-and-publish.yml:15: update your workflow using https://app.stepsecurity.io/secureworkflow/ordercloud-api/ordercloud-javascript-sdk/tag-and-publish.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/tag-and-publish.yml:18: update your workflow using https://app.stepsecurity.io/secureworkflow/ordercloud-api/ordercloud-javascript-sdk/tag-and-publish.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/tag-and-publish.yml:82: update your workflow using https://app.stepsecurity.io/secureworkflow/ordercloud-api/ordercloud-javascript-sdk/tag-and-publish.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/tag-and-publish.yml:91: update your workflow using https://app.stepsecurity.io/secureworkflow/ordercloud-api/ordercloud-javascript-sdk/tag-and-publish.yml/master?enable=pin","Info:   0 out of   5 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   1 third-party GitHubAction dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 30 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Vulnerabilities","score":5,"reason":"5 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: GHSA-968p-4wvh-cqc8","Warn: Project is vulnerable to: GHSA-jr5f-v2jv-69x6","Warn: Project is vulnerable to: GHSA-v6h2-p8h4-qcjw","Warn: Project is vulnerable to: GHSA-fjxv-7rqg-78g4","Warn: Project is vulnerable to: GHSA-52f5-9888-hmc6"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-22T08:23:37.091Z","repository_id":37514012,"created_at":"2025-08-22T08:23:37.091Z","updated_at":"2025-08-22T08:23:37.091Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31587820,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"online","status_checked_at":"2026-04-09T02:00:06.848Z","response_time":112,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-25T13:09:27.783Z","updated_at":"2026-04-09T05:32:24.347Z","avatar_url":"https://github.com/ordercloud-api.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- omit in toc --\u003e\r\n# OrderCloud\r\n\r\nThe OrderCloud SDK for Javascript is a modern client library for building solutions targeting the [Ordercloud eCommerce API](https://ordercloud.io/learn/ordercloud-basics/architecture). The SDK aims to greatly improve developer productivity and reduce errors.\r\n\r\n- [✨ Features](#-features)\r\n- [Requirements](#requirements)\r\n- [⚙️ Installation](#️-installation)\r\n- [➕ Adding it to your project](#-adding-it-to-your-project)\r\n  - [Using named imports](#using-named-imports)\r\n  - [Using wildcard import](#using-wildcard-import)\r\n  - [Using require](#using-require)\r\n- [🔐 Authentication](#-authentication)\r\n- [🔍 Filtering](#-filtering)\r\n- [👬 Impersonation](#-impersonation)\r\n- [Configuration](#configuration)\r\n- [Handling Errors 🐛](#handling-errors-)\r\n- [Interceptors](#interceptors)\r\n- [Cancelling Requests](#cancelling-requests)\r\n- [Async/Await](#asyncawait)\r\n- [Typescript Support](#typescript-support)\r\n  - [Understanding OrderCloud's models](#understanding-orderclouds-models)\r\n  - [Strongly Typed xp](#strongly-typed-xp)\r\n  - [Typescript utilities](#typescript-utilities)\r\n- [📄 License](#-license)\r\n- [🤝 Contributing](#-contributing)\r\n- [🆘 Getting Help](#-getting-help)\r\n\r\n## ✨ Features\r\n\r\n- Works both on the **browser** and **node.js**\r\n- ESM module available for bundlers that support it. This enables tree shaking - use only what you import.\r\n- Built-in Typescript support, no additional types package necessary\r\n- Full feature parity with API\r\n- Auto-generated [API reference](https://ordercloud-api.github.io/ordercloud-javascript-sdk)\r\n\r\n\u003e Coming from an older version? Check out the [migration guide](./MIGRATION_GUIDE.md) so you can upgrade to the latest and greatest.\r\n\r\n## Requirements\r\n\r\n[Axios](https://www.npmjs.com/package/axios) is a peer dependency of the OrderCloudSDK.\r\n\r\n\u003e Note: Peer dependencies are not installed automatically. They must be installed separately.\r\n\r\nWhy isn't axios a dependency of OrderCloud SDK? Since axios is a fairly popular http library and may already exist as a dependency in your project it is considered best practice to have it defined as a peer dependency. This way, there isn't a potential for two versions of axios to be installed which could result in weird bugs, not to mention a bloated javascript bundle.\r\n\r\n## ⚙️ Installation\r\n\r\nwith npm:\r\n\r\n```shell\r\nnpm install ordercloud-javascript-sdk --save\r\n```\r\n\r\nor\r\n\r\nwith yarn:\r\n\r\n```shell\r\nyarn add ordercloud-javascript-sdk\r\n```\r\n\r\n## ➕ Adding it to your project\r\n\r\n### Using named imports\r\n\r\nThis is the preferred method of importing the sdk for browser projects as it allows modern bundlers like webpack to tree shake the parts of the SDK that you aren't using, making your project more lean.\r\n\r\n```javascript\r\nimport { Products } from 'ordercloud-javascript-sdk';\r\n```\r\n\r\n### Using wildcard import\r\n\r\n```javascript\r\nimport * as OrderCloudSDK from 'ordercloud-javascript-sdk';\r\n```\r\n\r\n### Using require\r\n\r\n```javascript\r\nconst OrderCloudSDK = require('ordercloud-javascript-sdk');\r\n```\r\n\r\n## 🔐 Authentication\r\n\r\nWe'll need to get a token before we can make any API calls. The SDK offers five different ways of getting a token as part of the [Auth Resource](https://ordercloud-api.github.io/ordercloud-javascript-sdk/classes/Resources.Auth.html).\r\n\r\nWe'll use the login method for this example.\r\n\r\n```javascript\r\nimport { Auth, Tokens } from 'ordercloud-javascript-sdk';\r\n\r\nconst username = 'YOUR_USERNAME'; //username of the user logging in\r\nconst password = 'YOUR_PASSWORD'; //password of the user logging in\r\nconst clientID = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'; //clientID of the application the user is logging in to ([sign up for free](https://portal.ordercloud.io/register)\r\nconst scope = ['FullAccess']; //string array of [roles](https://ordercloud.io/knowledge-base/security-profiles) the application has access to\r\n\r\nAuth.Login(username, password, clientID, scope)\r\n  .then(response =\u003e {\r\n      //store token, now any subsequent calls will automatically set this token in the headers for you\r\n      const token = response.access_token;\r\n      Tokens.SetAccessToken(token)\r\n  })\r\n  .catch(err =\u003e console.log(err));\r\n```\r\n\r\n## 🔍 Filtering\r\n\r\nAll of the [filtering options](https://ordercloud.io/knowledge-base/advanced-querying#filtering)  you love from the API are available through the SDK as well. Simply build an object that matches the model of the item you're filtering on where the `value` is the value you'd like to filter on.\r\n\r\nLet's run through a couple scenarios and what the call will look like with the SDK:\r\n\r\nMy products where `xp.Featured` is `true`\r\n\r\n```javascript\r\nMe.ListProducts({ filters: { 'xp.Featured': true } })\r\n  .then(productList =\u003e console.log(productList));\r\n```\r\n\r\nMy orders submitted after April 20th, 2018\r\n\r\n```javascript\r\nMe.ListOrders({ filters: { DateSubmitted: '\u003e2020-04-20' } })\r\n  .then(orderList =\u003e console.log(orderList))\r\n```\r\n\r\nUsers with the last name starting with Smith:\r\n\r\n```javascript\r\nUsers.List('my-mock-buyerid', { filters: { LastName: 'Smith*' } })\r\n  .then(userList =\u003e console.log(userList));\r\n```\r\n\r\nUsers with the last name starting with Smith *or* users with the last name *ending* with Jones\r\n\r\n```javascript\r\nUsers.List('my-mock-buyerid', { filters: { LastName: 'Smith*|*Jones' } })\r\n  .then(userList =\u003e console.log(userList));\r\n```\r\n\r\nProducts where xp.Color is not red *and* not blue\r\n\r\n```javascript\r\nProducts.List({ filters: { 'xp.Color': ['!red', '!blue'] } })\r\n    .then(productList =\u003e console.log(productList));\r\n```\r\n\r\nAnd of course you can mix and match filters to your heart's content.\r\n\r\n## 👬 Impersonation\r\n\r\nImpersonation allows a seller user to make an API call on behalf of another user. The SDK enables this in two ways, each tackling different use cases.\r\n\r\nThe first method we'll talk about is best suited when you need to toggle between just two users during a session. You'll simply get an impersonation token, set it and then use the `As()` method available on every service to flag the SDK that you want to use the the stored token for that call.\r\n\r\n```javascript\r\nimport { Tokens, Me } from 'ordercloud-javascript-sdk';\r\n\r\n// set regular token\r\nconst myToken = 'YOUR_TOKEN';\r\nTokens.SetAccessToken(myToken);\r\n\r\n// set impersonation token\r\nconst myImpersonationToken = 'YOUR_IMPERSONATED_TOKEN'\r\nTokens.SetImpersonationToken(myImpersonationToken);\r\n\r\n// Get products for regular user\r\nMe.ListProducts()\r\n  .then(productList =\u003e console.log(productList))\r\n\r\n// Get products for the impersonated user\r\nMe.As().ListProducts()\r\n  .then(impersonatedProductList =\u003e console.log(impersonatedProductList))\r\n```\r\n\r\nAs you can see this method makes it very easy to toggle between impersonated calls and non-impersonated calls. But what if you have more than two tokens to toggle between? To address that scenario we recommend using the optional `requestOptions.accessToken` parameter. `requestOptions` is available as the last parameter on all sdk methods.\r\n\r\n```javascript\r\nimport { Me } from 'ordercloud-javascript-sdk';\r\n\r\nvar token1 = 'USER1_TOKEN';\r\nvar token2 = 'USER2_TOKEN';\r\nvar token3 = 'USER3_TOKEN';\r\n\r\n// Get products for user 1\r\nMe.ListProducts(null, { accessToken: token1 })\r\n  .then(user1ProductList =\u003e console.log(user1ProductList))\r\n\r\n// Get products for user 2\r\nMe.ListProducts(null, { accessToken: token2 })\r\n  .then(user2ProductList =\u003e console.log(user2ProductList))\r\n\r\n// Get products for user 3\r\nMe.ListProducts(null, { accessToken: token3 })\r\n  .then(user3ProductList =\u003e console.log(user3ProductList))\r\n```\r\n\r\n## Configuration\r\n\r\nThe [`Configuration`](https://ordercloud-api.github.io/ordercloud-javascript-sdk/classes/Resources.Configuration.html) service can be used to set sdk level [options](https://ordercloud-api.github.io/ordercloud-javascript-sdk/interfaces/sdkconfiguration).\r\n\r\nSimply set the options you need to override and the SDK will merge it with the default options object.\r\n\r\n```javascript\r\nimport { Configuration } from 'ordercloud-javascript-sdk';\r\n\r\nConfiguration.Set({\r\n  // This URL can be found on your dashboard or in the upper right hand context menu of your OrderCloud application in Sitecore Portal.\r\n  baseApiUrl: 'https://sandboxapi.ordercloud.io',\r\n  timeoutInMilliseconds: 20 * 1000\r\n})\r\n```\r\n\r\nSimilarly, you can see what the current options are by using the getter.\r\n\r\n```javascript\r\nimport { Configuration } from 'ordercloud-javascript-sdk';\r\n\r\nconst configuration = Configuration.Get();\r\nconsole.log(configuration); // the current sdk configuration\r\n```\r\n\r\n## Handling Errors 🐛\r\n\r\nThe SDK uses a custom error ([`OrderCloudError`](https://ordercloud-api.github.io/ordercloud-javascript-sdk/classes/orderclouderror)) to provide rich and useful information in the case of an error.\r\n\r\n```javascript\r\nProducts.Get('my-product')\r\n  .catch(error =\u003e {\r\n    if(error.isOrderCloudError) {\r\n      // the request was made and the API responded with a status code\r\n      // that falls outside of the range of 2xx, the error will be of type OrderCloudError\r\n      // https://ordercloud-api.github.io/ordercloud-javascript-sdk/classes/orderclouderror\r\n      console.log(error.message);\r\n      console.log(JSON.stringify(error.errors, null, 4));\r\n    } else if (error.request) {\r\n      // the request was made but no response received\r\n      // `error.request` is an instance of XMLHttpRequest in the browser and an instance of http.ClientRequest in node.js\r\n      console.log(error.request);\r\n    } else {\r\n      // Something happened in setting up the request that triggered an Error\r\n      console.log('Error', error.message);\r\n    }\r\n  })\r\n```\r\n\r\n## Interceptors\r\n\r\nYou can use [axios interceptors](https://github.com/axios/axios#interceptors) to intercept a request before it goes out to the API or to intercept a response before it gets handled by the SDK. This enables you to log, rewrite, or even retry calls.\r\n\r\nThe SDK does not use a custom axios instance, so you can set up your interceptors right off of axios.\r\n\r\n```javascript\r\n// Add a request interceptor\r\naxios.interceptors.request.use(function (config) {\r\n    // Do something before request is sent\r\n    return config;\r\n  }, function (error) {\r\n    // Do something with request error\r\n    return Promise.reject(error);\r\n  });\r\n\r\n// Add a response interceptor\r\naxios.interceptors.response.use(function (response) {\r\n    // Any status code that lie within the range of 2xx cause this function to trigger\r\n    // Do something with response data\r\n    return response;\r\n  }, function (error) {\r\n    // Any status codes that falls outside the range of 2xx cause this function to trigger\r\n    // Do something with response error\r\n    return Promise.reject(error);\r\n  });\r\n```\r\n\r\n## Cancelling Requests\r\n\r\nIn addition to `requestOptions.accessToken` the sdk provides `requestOptions.cancelToken` which enables [axios request cancellation](https://github.com/axios/axios#cancellation). This option is useful for cleaning up outstanding requests when changes in your user experience no longer require the data requested. For instance, you could use the cancel token to clean up outstanding requests [when your react component unmounts](https://reactjs.org/docs/hooks-effect.html#effects-with-cleanup).\r\n\r\n```javascript\r\nimport axios from 'axios';\r\nimport { Products } from 'ordercloud-javascript-sdk';\r\n\r\nconst signal = axios.CancelToken.source();\r\n\r\nProducts.List({search: 'Tennis balls'}, {cancelToken: signal.token})\r\n  .catch(ex =\u003e {\r\n    if (axios.isCancel(ex)) {\r\n      console.log(ex) // 'This request was cancelled!'\r\n    } else {\r\n      console.log(ex) // Normal ordercloud exception\r\n    }\r\n  })\r\n\r\n// Oops! I don't want to resolve this request anymore\r\nsignal.cancel('This request was cancelled!')\r\n```\r\n\r\n## Axios Adapters\r\n\r\nAdapters in Axios allow for custom handling of requests, which opens up possibilities for advanced functionalities such as caching, request mocking, and the option to switch HTTP APIs (for instance, from XHR to Fetch). You can use community created adapters, or create one yourself (just make sure it adheres to the [axios adapter interface](https://github.com/axios/axios/blob/v1.x/lib/adapters/README.md))\r\n\r\nLike all other sdk level options, Axios adapters can be defined with the Configuration service\r\n\r\n```typescript\r\nimport { Configuration } from 'ordercloud-javascript-sdk';\r\n\r\nConfiguration.Set({\r\n  baseApiUrl: 'https://sandboxapi.ordercloud.io',\r\n  timeoutInMilliseconds: 20 * 1000,\r\n  axiosAdapter: myAdapter\r\n})\r\n```\r\n\r\n## Async/Await\r\nAsync/Await is a special syntax to work with promises in a more comfortable fashion. Because the SDK is built with promises the syntax works right out of the box - simply add the `async` keyword to your outer function method.\r\n\r\n```javascript\r\n// with normal promises\r\n(() =\u003e {\r\n  Auth.Login('myusername', 'mypassword', 'myclientID', ['FullAccess'])\r\n    .then(authResponse =\u003e {\r\n      Tokens.SetAccessToken(authResponse.access_token)\r\n      Me.ListOrders().then(orderList =\u003e {\r\n        const firstOrder = orderList.Items[0]\r\n        console.log(firstOrder.Total)\r\n      })\r\n    })\r\n    .catch(err =\u003e {\r\n      console.log(err)\r\n    })\r\n})()\r\n```\r\n\r\n```javascript\r\n// with async/await\r\n(async () =\u003e {\r\n  try {\r\n    const authResponse = await Auth.Login('myusername', 'mypassword', 'myclientID', ['FullAccess'])\r\n    Tokens.SetAccessToken(authResponse.access_token)\r\n    const myOrders = await Me.ListOrders()\r\n    const firstOrder = myOrders.Items[0]\r\n  } catch (err) {\r\n    console.error(err)\r\n  }\r\n})()\r\n```\r\n\r\n\u003e NOTE: async/await is part of ECMAScript 2017 and is not supported in Internet Explorer and older browsers without first transpiling to ES5 so use with caution.\r\n\r\n## Typescript Support\r\n\r\nWhile Typescript is not required to use this project (we compile it down to ES5 javascript for you), it does mean there are some added benefits for our Typescript users. You will need a minimum of typescript version 3.5 for all features to work correctly.\r\n\r\n### Understanding OrderCloud's models\r\n\r\nBy default, properties of ordercloud models are required if their Create or Save operation requires them. For example the [`LineItem` model](https://ordercloud-api.github.io/ordercloud-javascript-sdk/interfaces/lineitem) has the properties `ProductID` and `Quantity` required. This is important to know if you need to define an object by type before using it.\r\n\r\n```typescript\r\nimport { LineItems, LineItem } from 'ordercloud-javascript-sdk';\r\n\r\nconst lineItem: LineItem = {\r\n  ProductID: 'my-awesome-product', // if this field is missing you get a type error!\r\n  Quantity: 2 // if this field is missing you get a type error!\r\n}\r\nLineItems.Create('Outgoing', 'my-order-id', lineItem)\r\n```\r\n\r\nThis works as expected and ensures a create or save always has the correct required parameters. However, if for example you need to perform a Patch operation (partial update), then you want all of the fields to be optional. To accomplish this you should use Typescript's built-in utility type [`Partial\u003cT\u003e`](https://www.typescriptlang.org/docs/handbook/utility-types.html#partialt)\r\n\r\n```typescript\r\nimport { LineItems, LineItem } from 'ordercloud-javascript-sdk';\r\n\r\nconst lineItem: Partial\u003cLineItem\u003e = {\r\n  // no type errors even though Quantity and ProductID are missing\r\n  ShippingAddressID: 'my-shipping-address-id'\r\n}\r\nLineItems.Patch('Outgoing', 'my-order-id', 'my-lineitem-id', lineItem)\r\n```\r\n\r\n### Strongly Typed xp\r\n\r\nExtended properties, or xp, is a [platform feature](https://ordercloud.io/knowledge-base/extended-properties) that allows you to extend the OrderCloud data model. This is modeled in the SDK using (by default) a Typescript [`any`](https://www.typescriptlang.org/docs/handbook/basic-types.html#any) type:\r\n\r\n```typescript\r\nconst category: Category = {};\r\ncategory.xp.Featured = true;\r\n```\r\n\r\nEven though `Featured` does not exist on the native model, the above code will compile and work just fine with the API. But you don't get any compile-time type-checking.\r\n\r\nAlternatively, the SDK provides generic versions of all models that allow you to provide a custom xp type:\r\n\r\n```typescript\r\ninterface MyCategoryXp {\r\n  Featured?: boolean;\r\n}\r\n\r\nconst category: Category\u003cMyCategoryXp\u003e = {};\r\ncategory.xp.Featured = true; // strongly typed!\r\n```\r\n\r\nThese custom models can then be used when calling any method in the SDK\r\n\r\n```typescript\r\nCategories.List\u003cCategory\u003cMyCategoryXp\u003e\u003e('mock-catalog-id')\r\n  .then(categoryList =\u003e {\r\n    const firstCategory = categoryList.Items[0];\r\n    const isFeatured = firstCategory.xp.Featured; // strongly typed!\r\n  })\r\n```\r\n\r\nA common alternative to the above example is to first define a custom interface that extends `Category\u003cMyCategoryXp\u003e`\r\n\r\n```typescript\r\ninterface MyCategoryXp {\r\n  Featured?: boolean;\r\n}\r\n\r\ninterface MyCategory extends Category\u003cMyCategoryXp\u003e {\r\n\r\n}\r\n\r\nCategories.List\u003cMyCategory\u003e('mock-catalog-id')\r\n  .then(categoryList =\u003e {\r\n    const firstCategory = categoryList.Items[0];\r\n    const isFeatured = firstCategory.xp.Featured; // strongly typed!\r\n  })\r\n```\r\n\r\nThis is nicer and especially preferable for models like `Order` which have many nested models each with their own `xp` fields that must be defined at the top level. For example: `Order\u003cOrderXp, FromUserXp, BillingAddressXp\u003e`. Declaring those 3 xp types once on a custom `MyOrder` interface is far cleaner than declaring them on every call to `Orders.Get` or `Orders.List`.\r\n\r\n### Typescript utilities\r\n\r\nThe sdk ships with various helpers and utilities that you may find useful. We also recommend using [Typescript's built-in utilities](https://www.typescriptlang.org/docs/handbook/utility-types.html) when possible.\r\n\r\n| Utility                                                                                                               | Description                                                                                                                                                                                                                          |\r\n|-----------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\r\n| [`ListPage\u003cT\u003e`](https://ordercloud-api.github.io/ordercloud-javascript-sdk/interfaces/listpage)                       | Takes in a type for the item in the list. For example `ListPage\u003cOrder\u003e` will be the type for an order list page.                                                                                                                     |\r\n| [`ListPageWithFacets\u003cT\u003e`]( https://ordercloud-api.github.io/ordercloud-javascript-sdk/interfaces/listpagewithfacets ) | Similar to `ListPage` but for [premium search](https://ordercloud.io/knowledge-base/introducing-premium-search) models. For example `ListPageWithFacets\u003cProduct\u003e` will be the type for a product list page.                          |\r\n| [`Searchable\u003cT\u003e`](https://ordercloud-api.github.io/ordercloud-javascript-sdk/types/Searchable.html)                              | Takes in a [`SearchableEndpoint`](https://ordercloud-api.github.io/ordercloud-javascript-sdk/types/Searchable.html) and returns the type for a valid `searchOn` field on list calls. For example `Searchable\u003c'Orders.List'\u003e`.           |\r\n| [`Sortable\u003cT\u003e`](https://ordercloud-api.github.io/ordercloud-javascript-sdk/types/Sortable.html)                                  | Takes in a [`SortableEndpoint`](https://ordercloud-api.github.io/ordercloud-javascript-sdk/types/Resources.SortableEndpoint.html) and returns the type for a valid `sortBy` field on list calls. For example `Sortable\u003c'Orders.List'\u003e`.                   |\r\n| [`Filters\u003cT\u003e`](https://ordercloud-api.github.io/ordercloud-javascript-sdk/types/Filters.html)                                    | Takes in an ordercloud model and returns the type for a valid `filter` field on list calls. For example `Filters\u003cProduct\u003e`. This also works for any custom models that extend an OrderCloud model, for example `Filters\u003cMyProduct\u003e`. |\r\n| [`PartialDeep\u003cT\u003e`](https://ordercloud-api.github.io/ordercloud-javascript-sdk/types/PartialDeep.html)                            | Similar to Typescript's [`Partial\u003cT\u003e`](https://www.typescriptlang.org/docs/handbook/utility-types.html#partialt) except works on nested properties as well.                                                                          |\r\n| [`RequiredDeep\u003cT\u003e`](https://ordercloud-api.github.io/ordercloud-javascript-sdk/types/RequiredDeep.html)                        | Similar to Typescript's [`Required\u003cT\u003e`](https://www.typescriptlang.org/docs/handbook/utility-types.html#requiredt) except works on nested properties as well.                                                                        |\r\n| [`DecodedToken`](https://ordercloud-api.github.io/ordercloud-javascript-sdk/interfaces/decodedtoken)                  | A type representing a decoded OrderCloud token                                                                                                                                                                                       |                                                                                                                                                                         |\r\n| [`MessageSenderPayloads`](https://ordercloud-api.github.io/ordercloud-javascript-sdk/types/MessageSenderPayloads.html)           | Takes in a type argument for the message type and resolves to the type for the message sender payload                                                                                                                                |\r\n## 📄 License\r\n\r\nOrderCloud's Javascript SDK is an open-sourced software licensed under the [MIT license](./LICENSE).\r\n\r\n## 🤝 Contributing\r\n\r\nCheck out our [Contributing](./CONTRIBUTING.md) guide.\r\n\r\n## 🆘 Getting Help\r\n\r\nIf you're new to OrderCloud, exploring the [documentation](https://ordercloud.io/) is recommended, especially the [Welcome to OrderCloud tutorial](https://ordercloud.io/learn/getting-started/welcome-to-ordercloud).\r\n\r\nFor programming questions, please [ask](https://stackoverflow.com/questions/ask?tags=ordercloud) on Stack Overflow.\r\n\r\nTo report a bug or request a feature specific to the SDK, please open an [issue](https://github.com/ordercloud-api/ordercloud-javascript-sdk/issues/new).\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fordercloud-api%2Fordercloud-javascript-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fordercloud-api%2Fordercloud-javascript-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fordercloud-api%2Fordercloud-javascript-sdk/lists"}